From 620039adfb7162e9a9ce6a9b90fd3f14d711c5fc Mon Sep 17 00:00:00 2001 From: Benjamin Kosnik Date: Tue, 12 Feb 2008 02:35:48 +0000 Subject: [PATCH] *: Remove all but contents of ext/pb_ds. 2008-02-11 Benjamin Kosnik * doc/html/*: Remove all but contents of ext/pb_ds. * doc/html/index.html: New. * doc/html/README: New. From-SVN: r132250 --- libstdc++-v3/ChangeLog | 6 + libstdc++-v3/doc/html/17_intro/BADNAMES | 182 - libstdc++-v3/doc/html/17_intro/C++STYLE | 399 -- libstdc++-v3/doc/html/17_intro/COPYING | 340 - libstdc++-v3/doc/html/17_intro/COPYING.DOC | 355 - libstdc++-v3/doc/html/17_intro/DESIGN | 859 --- libstdc++-v3/doc/html/17_intro/TODO | 164 - libstdc++-v3/doc/html/17_intro/abi.html | 991 --- libstdc++-v3/doc/html/17_intro/api.html | 290 - .../17_intro/backwards_compatibility.html | 1073 --- .../doc/html/17_intro/c++0x_status.html | 2290 ------- .../doc/html/17_intro/c++1998_status.html | 6004 ----------------- libstdc++-v3/doc/html/17_intro/confdeps.dot | 14 - libstdc++-v3/doc/html/17_intro/confdeps.png | Bin 3486 -> 0 bytes libstdc++-v3/doc/html/17_intro/configury.html | 305 - .../doc/html/17_intro/contribute.html | 135 - libstdc++-v3/doc/html/17_intro/howto.html | 737 -- libstdc++-v3/doc/html/17_intro/license.html | 119 - libstdc++-v3/doc/html/17_intro/porting.html | 992 --- libstdc++-v3/doc/html/17_intro/porting.texi | 570 -- .../doc/html/17_intro/tr1_status.html | 2322 ------- libstdc++-v3/doc/html/18_support/howto.html | 435 -- .../doc/html/19_diagnostics/howto.html | 127 - libstdc++-v3/doc/html/20_util/allocator.html | 554 -- libstdc++-v3/doc/html/20_util/howto.html | 234 - libstdc++-v3/doc/html/20_util/shared_ptr.html | 419 -- libstdc++-v3/doc/html/21_strings/gotw29a.txt | 159 - libstdc++-v3/doc/html/21_strings/howto.html | 472 -- .../doc/html/21_strings/stringtok_h.txt | 102 - .../doc/html/21_strings/stringtok_std_h.txt | 39 - libstdc++-v3/doc/html/22_locale/codecvt.html | 595 -- libstdc++-v3/doc/html/22_locale/ctype.html | 166 - libstdc++-v3/doc/html/22_locale/howto.html | 240 - libstdc++-v3/doc/html/22_locale/locale.html | 543 -- libstdc++-v3/doc/html/22_locale/messages.html | 461 -- .../doc/html/23_containers/howto.html | 457 -- .../doc/html/23_containers/wrappers_h.txt | 48 - libstdc++-v3/doc/html/24_iterators/howto.html | 200 - .../doc/html/25_algorithms/howto.html | 116 - libstdc++-v3/doc/html/26_numerics/howto.html | 179 - .../doc/html/27_io/binary_iostreams_kanze.txt | 51 - .../doc/html/27_io/binary_iostreams_kuehl.txt | 89 - libstdc++-v3/doc/html/27_io/howto.html | 779 --- libstdc++-v3/doc/html/README | 3 + libstdc++-v3/doc/html/configopts.html | 342 - libstdc++-v3/doc/html/debug.html | 474 -- libstdc++-v3/doc/html/documentation.html | 361 - libstdc++-v3/doc/html/ext/ballocator_doc.html | 426 -- libstdc++-v3/doc/html/ext/concurrence.html | 342 - libstdc++-v3/doc/html/ext/debug_mode.html | 578 -- libstdc++-v3/doc/html/ext/howto.html | 675 -- libstdc++-v3/doc/html/ext/mt_allocator.html | 560 -- libstdc++-v3/doc/html/ext/parallel_mode.html | 593 -- libstdc++-v3/doc/html/ext/sgiexts.html | 253 - libstdc++-v3/doc/html/faq/index.html | 1215 ---- libstdc++-v3/doc/html/index.html | 43 + libstdc++-v3/doc/html/install.html | 240 - libstdc++-v3/doc/html/lib3styles.css | 6 - libstdc++-v3/doc/html/test.html | 722 -- 59 files changed, 52 insertions(+), 31393 deletions(-) delete mode 100644 libstdc++-v3/doc/html/17_intro/BADNAMES delete mode 100644 libstdc++-v3/doc/html/17_intro/C++STYLE delete mode 100644 libstdc++-v3/doc/html/17_intro/COPYING delete mode 100644 libstdc++-v3/doc/html/17_intro/COPYING.DOC delete mode 100644 libstdc++-v3/doc/html/17_intro/DESIGN delete mode 100644 libstdc++-v3/doc/html/17_intro/TODO delete mode 100644 libstdc++-v3/doc/html/17_intro/abi.html delete mode 100644 libstdc++-v3/doc/html/17_intro/api.html delete mode 100644 libstdc++-v3/doc/html/17_intro/backwards_compatibility.html delete mode 100644 libstdc++-v3/doc/html/17_intro/c++0x_status.html delete mode 100644 libstdc++-v3/doc/html/17_intro/c++1998_status.html delete mode 100644 libstdc++-v3/doc/html/17_intro/confdeps.dot delete mode 100644 libstdc++-v3/doc/html/17_intro/confdeps.png delete mode 100644 libstdc++-v3/doc/html/17_intro/configury.html delete mode 100644 libstdc++-v3/doc/html/17_intro/contribute.html delete mode 100644 libstdc++-v3/doc/html/17_intro/howto.html delete mode 100644 libstdc++-v3/doc/html/17_intro/license.html delete mode 100644 libstdc++-v3/doc/html/17_intro/porting.html delete mode 100644 libstdc++-v3/doc/html/17_intro/porting.texi delete mode 100644 libstdc++-v3/doc/html/17_intro/tr1_status.html delete mode 100644 libstdc++-v3/doc/html/18_support/howto.html delete mode 100644 libstdc++-v3/doc/html/19_diagnostics/howto.html delete mode 100644 libstdc++-v3/doc/html/20_util/allocator.html delete mode 100644 libstdc++-v3/doc/html/20_util/howto.html delete mode 100644 libstdc++-v3/doc/html/20_util/shared_ptr.html delete mode 100644 libstdc++-v3/doc/html/21_strings/gotw29a.txt delete mode 100644 libstdc++-v3/doc/html/21_strings/howto.html delete mode 100644 libstdc++-v3/doc/html/21_strings/stringtok_h.txt delete mode 100644 libstdc++-v3/doc/html/21_strings/stringtok_std_h.txt delete mode 100644 libstdc++-v3/doc/html/22_locale/codecvt.html delete mode 100644 libstdc++-v3/doc/html/22_locale/ctype.html delete mode 100644 libstdc++-v3/doc/html/22_locale/howto.html delete mode 100644 libstdc++-v3/doc/html/22_locale/locale.html delete mode 100644 libstdc++-v3/doc/html/22_locale/messages.html delete mode 100644 libstdc++-v3/doc/html/23_containers/howto.html delete mode 100644 libstdc++-v3/doc/html/23_containers/wrappers_h.txt delete mode 100644 libstdc++-v3/doc/html/24_iterators/howto.html delete mode 100644 libstdc++-v3/doc/html/25_algorithms/howto.html delete mode 100644 libstdc++-v3/doc/html/26_numerics/howto.html delete mode 100644 libstdc++-v3/doc/html/27_io/binary_iostreams_kanze.txt delete mode 100644 libstdc++-v3/doc/html/27_io/binary_iostreams_kuehl.txt delete mode 100644 libstdc++-v3/doc/html/27_io/howto.html create mode 100644 libstdc++-v3/doc/html/README delete mode 100644 libstdc++-v3/doc/html/configopts.html delete mode 100644 libstdc++-v3/doc/html/debug.html delete mode 100644 libstdc++-v3/doc/html/documentation.html delete mode 100644 libstdc++-v3/doc/html/ext/ballocator_doc.html delete mode 100644 libstdc++-v3/doc/html/ext/concurrence.html delete mode 100644 libstdc++-v3/doc/html/ext/debug_mode.html delete mode 100644 libstdc++-v3/doc/html/ext/howto.html delete mode 100644 libstdc++-v3/doc/html/ext/mt_allocator.html delete mode 100644 libstdc++-v3/doc/html/ext/parallel_mode.html delete mode 100644 libstdc++-v3/doc/html/ext/sgiexts.html delete mode 100644 libstdc++-v3/doc/html/faq/index.html create mode 100644 libstdc++-v3/doc/html/index.html delete mode 100644 libstdc++-v3/doc/html/install.html delete mode 100644 libstdc++-v3/doc/html/lib3styles.css delete mode 100644 libstdc++-v3/doc/html/test.html diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 6d616d2391fc..45e7353159ae 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,9 @@ +2008-02-11 Benjamin Kosnik + + * doc/html/*: Remove all but contents of ext/pb_ds. + * doc/html/index.html: New. + * doc/html/README: New. + 2008-02-11 Benjamin Kosnik * doc/doxygen/mainpage.html: Add in corrected links. diff --git a/libstdc++-v3/doc/html/17_intro/BADNAMES b/libstdc++-v3/doc/html/17_intro/BADNAMES deleted file mode 100644 index a904704ee39f..000000000000 --- a/libstdc++-v3/doc/html/17_intro/BADNAMES +++ /dev/null @@ -1,182 +0,0 @@ - -This is the list of names "reserved to the implementation" that -have been claimed by certain compilers and system headers of interest, -and should not be used in the library. It will grow, of course. -We generally are interested in names that are not all-caps, except -for those like "_T" - -For Solarix: -_B -_C -_L -_N -_P -_S -_U -_X -_E1 -.. -_E24 - -Irix adds: -_A -_G - -MS adds: -_T - -BSD adds: -__used -__unused -__inline -_Complex -__istype -__maskrune -__tolower -__toupper -__wchar_t -__wint_t -_res -_res_ext -__tg_* - -For GCC: - - [Note that this list is out of date. It applies to the old - name-mangling; in G++ 3.0 and higher a different name-mangling is - used. In addition, many of the bugs relating to G++ interpreting - these names as operators have been fixed.] - - The full set of __* identifiers (combined from gcc/cp/lex.c and - gcc/cplus-dem.c) that are either old or new, but are definitely - recognized by the demangler, is: - -__aa -__aad -__ad -__addr -__adv -__aer -__als -__alshift -__amd -__ami -__aml -__amu -__aor -__apl -__array -__ars -__arshift -__as -__bit_and -__bit_ior -__bit_not -__bit_xor -__call -__cl -__cm -__cn -__co -__component -__compound -__cond -__convert -__delete -__dl -__dv -__eq -__er -__ge -__gt -__indirect -__le -__ls -__lt -__max -__md -__method_call -__mi -__min -__minus -__ml -__mm -__mn -__mult -__mx -__ne -__negate -__new -__nop -__nt -__nw -__oo -__op -__or -__pl -__plus -__postdecrement -__postincrement -__pp -__pt -__rf -__rm -__rs -__sz -__trunc_div -__trunc_mod -__truth_andif -__truth_not -__truth_orif -__vc -__vd -__vn - -SGI badnames: -__builtin_alloca -__builtin_fsqrt -__builtin_sqrt -__builtin_fabs -__builtin_dabs -__builtin_cast_f2i -__builtin_cast_i2f -__builtin_cast_d2ll -__builtin_cast_ll2d -__builtin_copy_dhi2i -__builtin_copy_i2dhi -__builtin_copy_dlo2i -__builtin_copy_i2dlo -__add_and_fetch -__sub_and_fetch -__or_and_fetch -__xor_and_fetch -__and_and_fetch -__nand_and_fetch -__mpy_and_fetch -__min_and_fetch -__max_and_fetch -__fetch_and_add -__fetch_and_sub -__fetch_and_or -__fetch_and_xor -__fetch_and_and -__fetch_and_nand -__fetch_and_mpy -__fetch_and_min -__fetch_and_max -__lock_test_and_set -__lock_release -__lock_acquire -__compare_and_swap -__synchronize -__high_multiply -__unix -__sgi -__linux__ -__i386__ -__i486__ -__cplusplus -__embedded_cplusplus -// long double conversion members mangled as __opr -// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html -_opr diff --git a/libstdc++-v3/doc/html/17_intro/C++STYLE b/libstdc++-v3/doc/html/17_intro/C++STYLE deleted file mode 100644 index 9eca719a32be..000000000000 --- a/libstdc++-v3/doc/html/17_intro/C++STYLE +++ /dev/null @@ -1,399 +0,0 @@ - -C++ Standard Library Coding Style Guidelines -------------------------------------- - -This library is written to appropriate C++ coding standards. As such, -it is intended to precede the recommendations of the GNU Coding -Standard, which can be referenced in full here: - -http://www.gnu.org/prep/standards/standards.html#Formatting - -The rest of this is also interesting reading, but skip the "Design -Advice" part. - -The GCC coding conventions are here, and are also useful: -http://gcc.gnu.org/codingconventions.html - -In addition, because it doesn't seem to be stated explicitly anywhere -else, there is an 80 column source limit. - -ChangeLog entries for member functions should use the -classname::member function name syntax as follows: - -1999-04-15 Dennis Ritchie - - * src/basic_file.cc (__basic_file::open): Fix thinko in - _G_HAVE_IO_FILE_OPEN bits. - -Notable areas of divergence from what may be previous local practice -(particularly for GNU C) include: - -01. Pointers and references - char* p = "flop"; - char& c = *p; - -NOT- - char *p = "flop"; // wrong - char &c = *p; // wrong - - Reason: In C++, definitions are mixed with executable code. Here, - p is being initialized, not *p. This is near-universal - practice among C++ programmers; it is normal for C hackers - to switch spontaneously as they gain experience. - -02. Operator names and parentheses - operator==(type) - -NOT- - operator == (type) // wrong - - Reason: The == is part of the function name. Separating - it makes the declaration look like an expression. - -03. Function names and parentheses - void mangle() - -NOT- - void mangle () // wrong - - Reason: no space before parentheses (except after a control-flow - keyword) is near-universal practice for C++. It identifies the - parentheses as the function-call operator or declarator, as - opposed to an expression or other overloaded use of parentheses. - -04. Template function indentation - template - void - template_function(args) - { } - -NOT- - template - void template_function(args) {}; - - Reason: In class definitions, without indentation whitespace is - needed both above and below the declaration to distinguish - it visually from other members. (Also, re: "typename" - rather than "class".) T often could be int, which is - not a class. ("class", here, is an anachronism.) - -05. Template class indentation - template - class basic_ios : public ios_base - { - public: - // Types: - }; - -NOT- - template - class basic_ios : public ios_base - { - public: - // Types: - }; - -NOT- - template - class basic_ios : public ios_base - { - public: - // Types: - }; - -06. Enumerators - enum - { - space = _ISspace, - print = _ISprint, - cntrl = _IScntrl - }; - -NOT- - enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; - -07. Member initialization lists - All one line, separate from class name. - - gribble::gribble() - : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - -NOT- - gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - -08. Try/Catch blocks - try - { - // - } - catch (...) - { - // - } - -NOT- - try { - // - } catch(...) { - // - } - -09. Member functions declarations and definitions - Keywords such as extern, static, export, explicit, inline, etc - go on the line above the function name. Thus - - virtual int - foo() - -NOT- - virtual int foo() - - Reason: GNU coding conventions dictate return types for functions - are on a separate line than the function name and parameter list - for definitions. For C++, where we have member functions that can - be either inline definitions or declarations, keeping to this - standard allows all member function names for a given class to be - aligned to the same margin, increasing readibility. - - -10. Invocation of member functions with "this->" - For non-uglified names, use this->name to call the function. - - this->sync() - -NOT- - sync() - - Reason: Koenig lookup. - -11. Namespaces - namespace std - { - blah blah blah; - } // namespace std - - -NOT- - - namespace std { - blah blah blah; - } // namespace std - -12. Spacing under protected and private in class declarations: - space above, none below - ie - - public: - int foo; - - -NOT- - public: - - int foo; - -13. Spacing WRT return statements. - no extra spacing before returns, no parenthesis - ie - - } - return __ret; - - -NOT- - } - - return __ret; - - -NOT- - - } - return (__ret); - - -14. Location of global variables. - All global variables of class type, whether in the "user visable" - space (e.g., cin) or the implementation namespace, must be defined - as a character array with the appropriate alignment and then later - re-initialized to the correct value. - - This is due to startup issues on certain platforms, such as AIX. - For more explanation and examples, see src/globals.cc. All such - variables should be contained in that file, for simplicity. - -15. Exception abstractions - Use the exception abstractions found in functexcept.h, which allow - C++ programmers to use this library with -fno-exceptions. (Even if - that is rarely advisable, it's a necessary evil for backwards - compatibility.) - -16. Exception error messages - All start with the name of the function where the exception is - thrown, and then (optional) descriptive text is added. Example: - - __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); - - Reason: The verbose terminate handler prints out exception::what(), - as well as the typeinfo for the thrown exception. As this is the - default terminate handler, by putting location info into the - exception string, a very useful error message is printed out for - uncaught exceptions. So useful, in fact, that non-programmers can - give useful error messages, and programmers can intelligently - speculate what went wrong without even using a debugger. - -17. The doxygen style guide to comments is a separate document, - see index. - -The library currently has a mixture of GNU-C and modern C++ coding -styles. The GNU C usages will be combed out gradually. - -Name patterns: - -For nonstandard names appearing in Standard headers, we are constrained -to use names that begin with underscores. This is called "uglification". -The convention is: - - Local and argument names: __[a-z].* - - Examples: __count __ix __s1 - - Type names and template formal-argument names: _[A-Z][^_].* - - Examples: _Helper _CharT _N - - Member data and function names: _M_.* - - Examples: _M_num_elements _M_initialize () - - Static data members, constants, and enumerations: _S_.* - - Examples: _S_max_elements _S_default_value - -Don't use names in the same scope that differ only in the prefix, -e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names. -(The most tempting of these seem to be and "_T" and "__sz".) - -Names must never have "__" internally; it would confuse name -unmanglers on some targets. Also, never use "__[0-9]", same reason. - --------------------------- - -[BY EXAMPLE] - -#ifndef _HEADER_ -#define _HEADER_ 1 - -namespace std -{ - class gribble - { - public: - gribble() throw(); - - gribble(const gribble&); - - explicit - gribble(int __howmany); - - gribble& - operator=(const gribble&); - - virtual - ~gribble() throw (); - - // Start with a capital letter, end with a period. - inline void - public_member(const char* __arg) const; - - // In-class function definitions should be restricted to one-liners. - int - one_line() { return 0 } - - int - two_lines(const char* arg) - { return strchr(arg, 'a'); } - - inline int - three_lines(); // inline, but defined below. - - // Note indentation. - template - void - public_template() const throw(); - - template - void - other_template(); - - private: - class _Helper; - - int _M_private_data; - int _M_more_stuff; - _Helper* _M_helper; - int _M_private_function(); - - enum _Enum - { - _S_one, - _S_two - }; - - static void - _S_initialize_library(); - }; - -// More-or-less-standard language features described by lack, not presence. -# ifndef _G_NO_LONGLONG - extern long long _G_global_with_a_good_long_name; // avoid globals! -# endif - - // Avoid in-class inline definitions, define separately; - // likewise for member class definitions: - inline int - gribble::public_member() const - { int __local = 0; return __local; } - - class gribble::_Helper - { - int _M_stuff; - - friend class gribble; - }; -} - -// Names beginning with "__": only for arguments and -// local variables; never use "__" in a type name, or -// within any name; never use "__[0-9]". - -#endif /* _HEADER_ */ - - -namespace std -{ - template // notice: "typename", not "class", no space - long_return_value_type - function_name(char* pointer, // "char *pointer" is wrong. - char* argument, - const Reference& ref) - { - // int a_local; /* wrong; see below. */ - if (test) - { - nested code - } - - int a_local = 0; // declare variable at first use. - - // char a, b, *p; /* wrong */ - char a = 'a'; - char b = a + 1; - char* c = "abc"; // each variable goes on its own line, always. - - // except maybe here... - for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) { - // ... - } - } - - gribble::gribble() - : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - - inline int - gribble::three_lines() - { - // doesn't fit in one line. - } -} // namespace std - - - diff --git a/libstdc++-v3/doc/html/17_intro/COPYING b/libstdc++-v3/doc/html/17_intro/COPYING deleted file mode 100644 index 623b6258a134..000000000000 --- a/libstdc++-v3/doc/html/17_intro/COPYING +++ /dev/null @@ -1,340 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/libstdc++-v3/doc/html/17_intro/COPYING.DOC b/libstdc++-v3/doc/html/17_intro/COPYING.DOC deleted file mode 100644 index 1a864561bd43..000000000000 --- a/libstdc++-v3/doc/html/17_intro/COPYING.DOC +++ /dev/null @@ -1,355 +0,0 @@ - GNU Free Documentation License - Version 1.1, March 2000 - - Copyright (C) 2000 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - -0. PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -written document "free" in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. - -This License is a kind of "copyleft", which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - - -1. APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The "Document", below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as "you". - -A "Modified Version" of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A "Secondary Section" is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The "Invariant Sections" are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. - -The "Cover Texts" are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. - -A "Transparent" copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not "Transparent" is called "Opaque". - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. - -The "Title Page" means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, "Title Page" means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - - -2. VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -3. COPYING IN QUANTITY - -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - - -4. MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. -B. List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has less than five). -C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. -D. Preserve all the copyright notices of the Document. -E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. -F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. -G. Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. -H. Include an unaltered copy of this License. -I. Preserve the section entitled "History", and its title, and add to - it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. -J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. -K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. -L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. -M. Delete any section entitled "Endorsements". Such a section - may not be included in the Modified Version. -N. Do not retitle any existing section as "Endorsements" - or to conflict in title with any Invariant Section. - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section entitled "Endorsements", provided it contains -nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - - -5. COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections entitled "History" -in the various original documents, forming one section entitled -"History"; likewise combine any sections entitled "Acknowledgements", -and any sections entitled "Dedications". You must delete all sections -entitled "Endorsements." - - -6. COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - -7. AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an "aggregate", and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. - - -8. TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. - - -9. TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - - -10. FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License "or any later version" applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. - - -ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - - Copyright (c) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License". - -If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write "no Front-Cover Texts" instead of -"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. diff --git a/libstdc++-v3/doc/html/17_intro/DESIGN b/libstdc++-v3/doc/html/17_intro/DESIGN deleted file mode 100644 index 5af3d9aed3be..000000000000 --- a/libstdc++-v3/doc/html/17_intro/DESIGN +++ /dev/null @@ -1,859 +0,0 @@ - -Standard C++ Library Design Document ------------------------------------- - -This is an overview of libstdc++-v3, with particular attention -to projects to be done and how they fit into the whole. - -The Library ------------ - -This paper is covers two major areas: - - - Features and policies not mentioned in the standard that - the quality of the library implementation depends on, including - extensions and "implementation-defined" features; - - - Plans for required but unimplemented library features and - optimizations to them. - -Overhead --------- - -The standard defines a large library, much larger than the standard -C library. A naive implementation would suffer substantial overhead -in compile time, executable size, and speed, rendering it unusable -in many (particularly embedded) applications. The alternative demands -care in construction, and some compiler support, but there is no -need for library subsets. - -What are the sources of this overhead? There are four main causes: - - - The library is specified almost entirely as templates, which - with current compilers must be included in-line, resulting in - very slow builds as tens or hundreds of thousands of lines - of function definitions are read for each user source file. - Indeed, the entire SGI STL, as well as the dos Reis valarray, - are provided purely as header files, largely for simplicity in - porting. Iostream/locale is (or will be) as large again. - - - The library is very flexible, specifying a multitude of hooks - where users can insert their own code in place of defaults. - When these hooks are not used, any time and code expended to - support that flexibility is wasted. - - - Templates are often described as causing to "code bloat". In - practice, this refers (when it refers to anything real) to several - independent processes. First, when a class template is manually - instantiated in its entirely, current compilers place the definitions - for all members in a single object file, so that a program linking - to one member gets definitions of all. Second, template functions - which do not actually depend on the template argument are, under - current compilers, generated anew for each instantiation, rather - than being shared with other instantiations. Third, some of the - flexibility mentioned above comes from virtual functions (both in - regular classes and template classes) which current linkers add - to the executable file even when they manifestly cannot be called. - - - The library is specified to use a language feature, exceptions, - which in the current gcc compiler ABI imposes a run time and - code space cost to handle the possibility of exceptions even when - they are not used. Under the new ABI (accessed with -fnew-abi), - there is a space overhead and a small reduction in code efficiency - resulting from lost optimization opportunities associated with - non-local branches associated with exceptions. - -What can be done to eliminate this overhead? A variety of coding -techniques, and compiler, linker and library improvements and -extensions may be used, as covered below. Most are not difficult, -and some are already implemented in varying degrees. - -Overhead: Compilation Time --------------------------- - -Providing "ready-instantiated" template code in object code archives -allows us to avoid generating and optimizing template instantiations -in each compilation unit which uses them. However, the number of such -instantiations that are useful to provide is limited, and anyway this -is not enough, by itself, to minimize compilation time. In particular, -it does not reduce time spent parsing conforming headers. - -Quicker header parsing will depend on library extensions and compiler -improvements. One approach is some variation on the techniques -previously marketed as "pre-compiled headers", now standardized as -support for the "export" keyword. "Exported" template definitions -can be placed (once) in a "repository" -- really just a library, but -of template definitions rather than object code -- to be drawn upon -at link time when an instantiation is needed, rather than placed in -header files to be parsed along with every compilation unit. - -Until "export" is implemented we can put some of the lengthy template -definitions in #if guards or alternative headers so that users can skip -over the the full definitions when they need only the ready-instantiated -specializations. - -To be precise, this means that certain headers which define -templates which users normally use only for certain arguments -can be instrumented to avoid exposing the template definitions -to the compiler unless a macro is defined. For example, in -, we might have: - - template class basic_string { - ... // member declarations - }; - ... // operator declarations - - #ifdef _STRICT_ISO_ - # if _G_NO_TEMPLATE_EXPORT - # include // headers needed by definitions - # ... - # include // member and global template definitions. - # endif - #endif - -Users who compile without specifying a strict-ISO-conforming flag -would not see many of the template definitions they now see, and rely -instead on ready-instantiated specializations in the library. This -technique would be useful for the following substantial components: -string, locale/iostreams, valarray. It would *not* be useful or -usable with the following: containers, algorithms, iterators, -allocator. Since these constitute a large (though decreasing) -fraction of the library, the benefit the technique offers is -limited. - -The language specifies the semantics of the "export" keyword, but -the gcc compiler does not yet support it. When it does, problems -with large template inclusions can largely disappear, given some -minor library reorganization, along with the need for the apparatus -described above. - -Overhead: Flexibility Cost --------------------------- - -The library offers many places where users can specify operations -to be performed by the library in place of defaults. Sometimes -this seems to require that the library use a more-roundabout, and -possibly slower, way to accomplish the default requirements than -would be used otherwise. - -The primary protection against this overhead is thorough compiler -optimization, to crush out layers of inline function interfaces. -Kuck & Associates has demonstrated the practicality of this kind -of optimization. - -The second line of defense against this overhead is explicit -specialization. By defining helper function templates, and writing -specialized code for the default case, overhead can be eliminated -for that case without sacrificing flexibility. This takes full -advantage of any ability of the optimizer to crush out degenerate -code. - -The library specifies many virtual functions which current linkers -load even when they cannot be called. Some minor improvements to the -compiler and to ld would eliminate any such overhead by simply -omitting virtual functions that the complete program does not call. -A prototype of this work has already been done. For targets where -GNU ld is not used, a "pre-linker" could do the same job. - -The main areas in the standard interface where user flexibility -can result in overhead are: - - - Allocators: Containers are specified to use user-definable - allocator types and objects, making tuning for the container - characteristics tricky. - - - Locales: the standard specifies locale objects used to implement - iostream operations, involving many virtual functions which use - streambuf iterators. - - - Algorithms and containers: these may be instantiated on any type, - frequently duplicating code for identical operations. - - - Iostreams and strings: users are permitted to use these on their - own types, and specify the operations the stream must use on these - types. - -Note that these sources of overhead are _avoidable_. The techniques -to avoid them are covered below. - -Code Bloat ----------- - -In the SGI STL, and in some other headers, many of the templates -are defined "inline" -- either explicitly or by their placement -in class definitions -- which should not be inline. This is a -source of code bloat. Matt had remarked that he was relying on -the compiler to recognize what was too big to benefit from inlining, -and generate it out-of-line automatically. However, this also can -result in code bloat except where the linker can eliminate the extra -copies. - -Fixing these cases will require an audit of all inline functions -defined in the library to determine which merit inlining, and moving -the rest out of line. This is an issue mainly in chapters 23, 25, and -27. Of course it can be done incrementally, and we should generally -accept patches that move large functions out of line and into ".tcc" -files, which can later be pulled into a repository. Compiler/linker -improvements to recognize very large inline functions and move them -out-of-line, but shared among compilation units, could make this -work unnecessary. - -Pre-instantiating template specializations currently produces large -amounts of dead code which bloats statically linked programs. The -current state of the static library, libstdc++.a, is intolerable on -this account, and will fuel further confused speculation about a need -for a library "subset". A compiler improvement that treats each -instantiated function as a separate object file, for linking purposes, -would be one solution to this problem. An alternative would be to -split up the manual instantiation files into dozens upon dozens of -little files, each compiled separately, but an abortive attempt at -this was done for and, though it is far from complete, it -is already a nuisance. A better interim solution (just until we have -"export") is badly needed. - -When building a shared library, the current compiler/linker cannot -automatically generate the instantiatiations needed. This creates a -miserable situation; it means any time something is changed in the -library, before a shared library can be built someone must manually -copy the declarations of all templates that are needed by other parts -of the library to an "instantiation" file, and add it to the build -system to be compiled and linked to the library. This process is -readily automated, and should be automated as soon as possible. -Users building their own shared libraries experience identical -frustrations. - -Sharing common aspects of template definitions among instantiations -can radically reduce code bloat. The compiler could help a great -deal here by recognizing when a function depends on nothing about -a template parameter, or only on its size, and giving the resulting -function a link-name "equate" that allows it to be shared with other -instantiations. Implementation code could take advantage of the -capability by factoring out code that does not depend on the template -argument into separate functions to be merged by the compiler. - -Until such a compiler optimization is implemented, much can be done -manually (if tediously) in this direction. One such optimization is -to derive class templates from non-template classes, and move as much -implementation as possible into the base class. Another is to partial- -specialize certain common instantiations, such as vector, to share -code for instantiations on all types T. While these techniques work, -they are far from the complete solution that a compiler improvement -would afford. - -Overhead: Expensive Language Features -------------------------------------- - -The main "expensive" language feature used in the standard library -is exception support, which requires compiling in cleanup code with -static table data to locate it, and linking in library code to use -the table. For small embedded programs the amount of such library -code and table data is assumed by some to be excessive. Under the -"new" ABI this perception is generally exaggerated, although in some -cases it may actually be excessive. - -To implement a library which does not use exceptions directly is -not difficult given minor compiler support (to "turn off" exceptions -and ignore exception constructs), and results in no great library -maintenance difficulties. To be precise, given "-fno-exceptions", -the compiler should treat "try" blocks as ordinary blocks, and -"catch" blocks as dead code to ignore or eliminate. Compiler -support is not strictly necessary, except in the case of "function -try blocks"; otherwise the following macros almost suffice: - - #define throw(X) - #define try if (true) - #define catch(X) else if (false) - -However, there may be a need to use function try blocks in the -library implementation, and use of macros in this way can make -correct diagnostics impossible. Furthermore, use of this scheme -would require the library to call a function to re-throw exceptions -from a try block. Implementing the above semantics in the compiler -is preferable. - -Given the support above (however implemented) it only remains to -replace code that "throws" with a call to a well-documented "handler" -function in a separate compilation unit which may be replaced by -the user. The main source of exceptions that would be difficult -for users to avoid is memory allocation failures, but users can -define their own memory allocation primitives that never throw. -Otherwise, the complete list of such handlers, and which library -functions may call them, would be needed for users to be able to -implement the necessary substitutes. (Fortunately, they have the -source code.) - -Opportunities -------------- - -The template capabilities of C++ offer enormous opportunities for -optimizing common library operations, well beyond what would be -considered "eliminating overhead". In particular, many operations -done in Glibc with macros that depend on proprietary language -extensions can be implemented in pristine Standard C++. For example, -the chapter 25 algorithms, and even C library functions such as strchr, -can be specialized for the case of static arrays of known (small) size. - -Detailed optimization opportunities are identified below where -the component where they would appear is discussed. Of course new -opportunities will be identified during implementation. - -Unimplemented Required Library Features ---------------------------------------- - -The standard specifies hundreds of components, grouped broadly by -chapter. These are listed in excruciating detail in the CHECKLIST -file. - - 17 general - 18 support - 19 diagnostics - 20 utilities - 21 string - 22 locale - 23 containers - 24 iterators - 25 algorithms - 26 numerics - 27 iostreams - Annex D backward compatibility - -Anyone participating in implementation of the library should obtain -a copy of the standard, ISO 14882. People in the U.S. can obtain an -electronic copy for US$18 from ANSI's web site. Those from other -countries should visit http://www.iso.ch/ to find out the location -of their country's representation in ISO, in order to know who can -sell them a copy. - -The emphasis in the following sections is on unimplemented features -and optimization opportunities. - -Chapter 17 General -------------------- - -Chapter 17 concerns overall library requirements. - -The standard doesn't mention threads. A multi-thread (MT) extension -primarily affects operators new and delete (18), allocator (20), -string (21), locale (22), and iostreams (27). The common underlying -support needed for this is discussed under chapter 20. - -The standard requirements on names from the C headers create a -lot of work, mostly done. Names in the C headers must be visible -in the std:: and sometimes the global namespace; the names in the -two scopes must refer to the same object. More stringent is that -Koenig lookup implies that any types specified as defined in std:: -really are defined in std::. Names optionally implemented as -macros in C cannot be macros in C++. (An overview may be read at -). The scripts "inclosure" -and "mkcshadow", and the directories shadow/ and cshadow/, are the -beginning of an effort to conform in this area. - -A correct conforming definition of C header names based on underlying -C library headers, and practical linking of conforming namespaced -customer code with third-party C libraries depends ultimately on -an ABI change, allowing namespaced C type names to be mangled into -type names as if they were global, somewhat as C function names in a -namespace, or C++ global variable names, are left unmangled. Perhaps -another "extern" mode, such as 'extern "C-global"' would be an -appropriate place for such type definitions. Such a type would -affect mangling as follows: - - namespace A { - struct X {}; - extern "C-global" { // or maybe just 'extern "C"' - struct Y {}; - }; - } - void f(A::X*); // mangles to f__FPQ21A1X - void f(A::Y*); // mangles to f__FP1Y - -(It may be that this is really the appropriate semantics for regular -'extern "C"', and 'extern "C-global"', as an extension, would not be -necessary.) This would allow functions declared in non-standard C headers -(and thus fixable by neither us nor users) to link properly with functions -declared using C types defined in properly-namespaced headers. The -problem this solves is that C headers (which C++ programmers do persist -in using) frequently forward-declare C struct tags without including -the header where the type is defined, as in - - struct tm; - void munge(tm*); - -Without some compiler accommodation, munge cannot be called by correct -C++ code using a pointer to a correctly-scoped tm* value. - -The current C headers use the preprocessor extension "#include_next", -which the compiler complains about when run "-pedantic". -(Incidentally, it appears that "-fpedantic" is currently ignored, -probably a bug.) The solution in the C compiler is to use -"-isystem" rather than "-I", but unfortunately in g++ this seems -also to wrap the whole header in an 'extern "C"' block, so it's -unusable for C++ headers. The correct solution appears to be to -allow the various special include-directory options, if not given -an argument, to affect subsequent include-directory options additively, -so that if one said - - -pedantic -iprefix $(prefix) \ - -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ - -iwithprefix -I g++-v3/ext - -the compiler would search $(prefix)/g++-v3 and not report -pedantic warnings for files found there, but treat files in -$(prefix)/g++-v3/ext pedantically. (The undocumented semantics -of "-isystem" in g++ stink. Can they be rescinded? If not it -must be replaced with something more rationally behaved.) - -All the C headers need the treatment above; in the standard these -headers are mentioned in various chapters. Below, I have only -mentioned those that present interesting implementation issues. - -The components identified as "mostly complete", below, have not been -audited for conformance. In many cases where the library passes -conformance tests we have non-conforming extensions that must be -wrapped in #if guards for "pedantic" use, and in some cases renamed -in a conforming way for continued use in the implementation regardless -of conformance flags. - -The STL portion of the library still depends on a header -stl/bits/stl_config.h full of #ifdef clauses. This apparatus -should be replaced with autoconf/automake machinery. - -The SGI STL defines a type_traits<> template, specialized for -many types in their code including the built-in numeric and -pointer types and some library types, to direct optimizations of -standard functions. The SGI compiler has been extended to generate -specializations of this template automatically for user types, -so that use of STL templates on user types can take advantage of -these optimizations. Specializations for other, non-STL, types -would make more optimizations possible, but extending the gcc -compiler in the same way would be much better. Probably the next -round of standardization will ratify this, but probably with -changes, so it probably should be renamed to place it in the -implementation namespace. - -The SGI STL also defines a large number of extensions visible in -standard headers. (Other extensions that appear in separate headers -have been sequestered in subdirectories ext/ and backward/.) All -these extensions should be moved to other headers where possible, -and in any case wrapped in a namespace (not std!), and (where kept -in a standard header) girded about with macro guards. Some cannot be -moved out of standard headers because they are used to implement -standard features. The canonical method for accommodating these -is to use a protected name, aliased in macro guards to a user-space -name. Unfortunately C++ offers no satisfactory template typedef -mechanism, so very ad-hoc and unsatisfactory aliasing must be used -instead. - -Implementation of a template typedef mechanism should have the highest -priority among possible extensions, on the same level as implementation -of the template "export" feature. - -Chapter 18 Language support ----------------------------- - -Headers: -C headers: - (also 21, 25, 26) - -This defines the built-in exceptions, rtti, numeric_limits<>, -operator new and delete. Much of this is provided by the -compiler in its static runtime library. - -Work to do includes defining numeric_limits<> specializations in -separate files for all target architectures. Values for integer types -except for bool and wchar_t are readily obtained from the C header -, but values for the remaining numeric types (bool, wchar_t, -float, double, long double) must be entered manually. This is -largely dog work except for those members whose values are not -easily deduced from available documentation. Also, this involves -some work in target configuration to identify the correct choice of -file to build against and to install. - -The definitions of the various operators new and delete must be -made thread-safe, which depends on a portable exclusion mechanism, -discussed under chapter 20. Of course there is always plenty of -room for improvements to the speed of operators new and delete. - -, in Glibc, defines some macros that gcc does not allow to -be wrapped into an inline function. Probably this header will demand -attention whenever a new target is chosen. The functions atexit(), -exit(), and abort() in cstdlib have different semantics in C++, so -must be re-implemented for C++. - -Chapter 19 Diagnostics ------------------------ - -Headers: -C headers: - -This defines the standard exception objects, which are "mostly complete". -Cygnus has a version, and now SGI provides a slightly different one. -It makes little difference which we use. - -The C global name "errno", which C allows to be a variable or a macro, -is required in C++ to be a macro. For MT it must typically result in -a function call. - -Chapter 20 Utilities ---------------------- -Headers: -C header: (also in 18) - -SGI STL provides "mostly complete" versions of all the components -defined in this chapter. However, the auto_ptr<> implementation -is known to be wrong. Furthermore, the standard definition of it -is known to be unimplementable as written. A minor change to the -standard would fix it, and auto_ptr<> should be adjusted to match. - -Multi-threading affects the allocator implementation, and there must -be configuration/installation choices for different users' MT -requirements. Anyway, users will want to tune allocator options -to support different target conditions, MT or no. - -The primitives used for MT implementation should be exposed, as an -extension, for users' own work. We need cross-CPU "mutex" support, -multi-processor shared-memory atomic integer operations, and single- -processor uninterruptible integer operations, and all three configurable -to be stubbed out for non-MT use, or to use an appropriately-loaded -dynamic library for the actual runtime environment, or statically -compiled in for cases where the target architecture is known. - -Chapter 21 String ------------------- -Headers: -C headers: (also in 27) - (also in 18, 25, 26) - -We have "mostly-complete" char_traits<> implementations. Many of the -char_traits operations might be optimized further using existing -proprietary language extensions. - -We have a "mostly-complete" basic_string<> implementation. The work -to manually instantiate char and wchar_t specializations in object -files to improve link-time behavior is extremely unsatisfactory, -literally tripling library-build time with no commensurate improvement -in static program link sizes. It must be redone. (Similar work is -needed for some components in chapters 22 and 27.) - -Other work needed for strings is MT-safety, as discussed under the -chapter 20 heading. - -The standard C type mbstate_t from and used in char_traits<> -must be different in C++ than in C, because in C++ the default constructor -value mbstate_t() must be the "base" or "ground" sequence state. -(According to the likely resolution of a recently raised Core issue, -this may become unnecessary. However, there are other reasons to -use a state type not as limited as whatever the C library provides.) -If we might want to provide conversions from (e.g.) internally- -represented EUC-wide to externally-represented Unicode, or vice- -versa, the mbstate_t we choose will need to be more accommodating -than what might be provided by an underlying C library. - -There remain some basic_string template-member functions which do -not overload properly with their non-template brethren. The infamous -hack akin to what was done in vector<> is needed, to conform to -23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', -or incomplete, are so marked for this reason. - -Replacing the string iterators, which currently are simple character -pointers, with class objects would greatly increase the safety of the -client interface, and also permit a "debug" mode in which range, -ownership, and validity are rigorously checked. The current use of -raw pointers as string iterators is evil. vector<> iterators need the -same treatment. Note that the current implementation freely mixes -pointers and iterators, and that must be fixed before safer iterators -can be introduced. - -Some of the functions in are different from the C version. -generally overloaded on const and non-const argument pointers. For -example, in strchr is overloaded. The functions isupper -etc. in typically implemented as macros in C are functions -in C++, because they are overloaded with others of the same name -defined in . - -Many of the functions required in and cannot be -implemented using underlying C facilities on intended targets because -such facilities only partly exist. - -Chapter 22 Locale ------------------- -Headers: -C headers: - -We have a "mostly complete" class locale, with the exception of -code for constructing, and handling the names of, named locales. -The ways that locales are named (particularly when categories -(e.g. LC_TIME, LC_COLLATE) are different) varies among all target -environments. This code must be written in various versions and -chosen by configuration parameters. - -Members of many of the facets defined in are stubs. Generally, -there are two sets of facets: the base class facets (which are supposed -to implement the "C" locale) and the "byname" facets, which are supposed -to read files to determine their behavior. The base ctype<>, collate<>, -and numpunct<> facets are "mostly complete", except that the table of -bitmask values used for "is" operations, and corresponding mask values, -are still defined in libio and just included/linked. (We will need to -implement these tables independently, soon, but should take advantage -of libio where possible.) The num_put<>::put members for integer types -are "mostly complete". - -A complete list of what has and has not been implemented may be -found in CHECKLIST. However, note that the current definition of -codecvt is wrong. It should simply write -out the raw bytes representing the wide characters, rather than -trying to convert each to a corresponding single "char" value. - -Some of the facets are more important than others. Specifically, -the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets -are used by other library facilities defined in , , -and , and the codecvt<> facet is used by basic_filebuf<> -in , so a conforming iostream implementation depends on -these. - -The "long long" type eventually must be supported, but code mentioning -it should be wrapped in #if guards to allow pedantic-mode compiling. - -Performance of num_put<> and num_get<> depend critically on -caching computed values in ios_base objects, and on extensions -to the interface with streambufs. - -Specifically: retrieving a copy of the locale object, extracting -the needed facets, and gathering data from them, for each call to -(e.g.) operator<< would be prohibitively slow. To cache format -data for use by num_put<> and num_get<> we have a _Format_cache<> -object stored in the ios_base::pword() array. This is constructed -and initialized lazily, and is organized purely for utility. It -is discarded when a new locale with different facets is imbued. - -Using only the public interfaces of the iterator arguments to the -facet functions would limit performance by forbidding "vector-style" -character operations. The streambuf iterator optimizations are -described under chapter 24, but facets can also bypass the streambuf -iterators via explicit specializations and operate directly on the -streambufs, and use extended interfaces to get direct access to the -streambuf internal buffer arrays. These extensions are mentioned -under chapter 27. These optimizations are particularly important -for input parsing. - -Unused virtual members of locale facets can be omitted, as mentioned -above, by a smart linker. - -Chapter 23 Containers ----------------------- -Headers: - -All the components in chapter 23 are implemented in the SGI STL. -They are "mostly complete"; they include a large number of -nonconforming extensions which must be wrapped. Some of these -are used internally and must be renamed or duplicated. - -The SGI components are optimized for large-memory environments. For -embedded targets, different criteria might be more appropriate. Users -will want to be able to tune this behavior. We should provide -ways for users to compile the library with different memory usage -characteristics. - -A lot more work is needed on factoring out common code from different -specializations to reduce code size here and in chapter 25. The -easiest fix for this would be a compiler/ABI improvement that allows -the compiler to recognize when a specialization depends only on the -size (or other gross quality) of a template argument, and allow the -linker to share the code with similar specializations. In its -absence, many of the algorithms and containers can be partial- -specialized, at least for the case of pointers, but this only solves -a small part of the problem. Use of a type_traits-style template -allows a few more optimization opportunities, more if the compiler -can generate the specializations automatically. - -As an optimization, containers can specialize on the default allocator -and bypass it, or take advantage of details of its implementation -after it has been improved upon. - -Replacing the vector iterators, which currently are simple element -pointers, with class objects would greatly increase the safety of the -client interface, and also permit a "debug" mode in which range, -ownership, and validity are rigorously checked. The current use of -pointers for iterators is evil. - -As mentioned for chapter 24, the deque iterator is a good example of -an opportunity to implement a "staged" iterator that would benefit -from specializations of some algorithms. - -Chapter 24 Iterators ---------------------- -Headers: - -Standard iterators are "mostly complete", with the exception of -the stream iterators, which are not yet templatized on the -stream type. Also, the base class template iterator<> appears -to be wrong, so everything derived from it must also be wrong, -currently. - -The streambuf iterators (currently located in stl/bits/std_iterator.h, -but should be under bits/) can be rewritten to take advantage of -friendship with the streambuf implementation. - -Matt Austern has identified opportunities where certain iterator -types, particularly including streambuf iterators and deque -iterators, have a "two-stage" quality, such that an intermediate -limit can be checked much more quickly than the true limit on -range operations. If identified with a member of iterator_traits, -algorithms may be specialized for this case. Of course the -iterators that have this quality can be identified by specializing -a traits class. - -Many of the algorithms must be specialized for the streambuf -iterators, to take advantage of block-mode operations, in order -to allow iostream/locale operations' performance not to suffer. -It may be that they could be treated as staged iterators and -take advantage of those optimizations. - -Chapter 25 Algorithms ----------------------- -Headers: -C headers: (also in 18, 21, 26)) - -The algorithms are "mostly complete". As mentioned above, they -are optimized for speed at the expense of code and data size. - -Specializations of many of the algorithms for non-STL types would -give performance improvements, but we must use great care not to -interfere with fragile template overloading semantics for the -standard interfaces. Conventionally the standard function template -interface is an inline which delegates to a non-standard function -which is then overloaded (this is already done in many places in -the library). Particularly appealing opportunities for the sake of -iostream performance are for copy and find applied to streambuf -iterators or (as noted elsewhere) for staged iterators, of which -the streambuf iterators are a good example. - -The bsearch and qsort functions cannot be overloaded properly as -required by the standard because gcc does not yet allow overloading -on the extern-"C"-ness of a function pointer. - -Chapter 26 Numerics --------------------- -Headers: -C headers: , (also 18, 21, 25) - -Numeric components: Gabriel dos Reis's valarray, Drepper's complex, -and the few algorithms from the STL are "mostly done". Of course -optimization opportunities abound for the numerically literate. It -is not clear whether the valarray implementation really conforms -fully, in the assumptions it makes about aliasing (and lack thereof) -in its arguments. - -The C div() and ldiv() functions are interesting, because they are the -only case where a C library function returns a class object by value. -Since the C++ type div_t must be different from the underlying C type -(which is in the wrong namespace) the underlying functions div() and -ldiv() cannot be re-used efficiently. Fortunately they are trivial to -re-implement. - -Chapter 27 Iostreams ---------------------- -Headers: - -C headers: (also in 21) - -Iostream is currently in a very incomplete state. , , -ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and -basic_ostream<> are well along, but basic_istream<> has had little work -done. The standard stream objects, and have been -started; basic_filebuf<> "write" functions have been implemented just -enough to do "hello, world". - -Most of the istream and ostream operators << and >> (with the exception -of the op<<(integer) ones) have not been changed to use locale primitives, -sentry objects, or char_traits members. - -All these templates should be manually instantiated for char and -wchar_t in a way that links only used members into user programs. - -Streambuf is fertile ground for optimization extensions. An extended -interface giving iterator access to its internal buffer would be very -useful for other library components. - -Iostream operations (primarily operators << and >>) can take advantage -of the case where user code has not specified a locale, and bypass locale -operations entirely. The current implementation of op<::put, -for the integer types, demonstrates how they can cache encoding details -from the locale on each operation. There is lots more room for -optimization in this area. - -The definition of the relationship between the standard streams -cout et al. and stdout et al. requires something like a "stdiobuf". -The SGI solution of using double-indirection to actually use a -stdio FILE object for buffering is unsatisfactory, because it -interferes with peephole loop optimizations. - -The header work has begun. stringbuf can benefit from -friendship with basic_string<> and basic_string<>::_Rep to use -those objects directly as buffers, and avoid allocating and making -copies. - -The basic_filebuf<> template is a complex beast. It is specified to -use the locale facet codecvt<> to translate characters between native -files and the locale character encoding. In general this involves -two buffers, one of "char" representing the file and another of -"char_type", for the stream, with codecvt<> translating. The process -is complicated by the variable-length nature of the translation, and -the need to seek to corresponding places in the two representations. -For the case of basic_filebuf, when no translation is needed, -a single buffer suffices. A specialized filebuf can be used to reduce -code space overhead when no locale has been imbued. Matt Austern's -work at SGI will be useful, perhaps directly as a source of code, or -at least as an example to draw on. - -Filebuf, almost uniquely (cf. operator new), depends heavily on -underlying environmental facilities. In current releases iostream -depends fairly heavily on libio constant definitions, but it should -be made independent. It also depends on operating system primitives -for file operations. There is immense room for optimizations using -(e.g.) mmap for reading. The shadow/ directory wraps, besides the -standard C headers, the libio.h and unistd.h headers, for use mainly -by filebuf. These wrappings have not been completed, though there -is scaffolding in place. - -The encapulation of certain C header names presents an -interesting problem. It is possible to define an inline std::fprintf() -implemented in terms of the 'extern "C"' vfprintf(), but there is no -standard vfscanf() to use to implement std::fscanf(). It appears that -vfscanf but be re-implemented in C++ for targets where no vfscanf -extension has been defined. This is interesting in that it seems -to be the only significant case in the C library where this kind of -rewriting is necessary. (Of course Glibc provides the vfscanf() -extension.) (The functions related to exit() must be rewritten -for other reasons.) - - -Annex D -------- -Headers: - -Annex D defines many non-library features, and many minor -modifications to various headers, and a complete header. -It is "mostly done", except that the libstdc++-2 -header has not been adopted into the library, or checked to -verify that it matches the draft in those details that were -clarified by the committee. Certainly it must at least be -moved into the std namespace. - -We still need to wrap all the deprecated features in #if guards -so that pedantic compile modes can detect their use. - -Nonstandard Extensions ----------------------- -Headers: - (etc.) - -User code has come to depend on a variety of nonstandard components -that we must not omit. Much of this code can be adopted from -libstdc++-v2 or from the SGI STL. This particularly includes -, , and various SGI extensions such -as . Many of these are already placed in the -subdirectories ext/ and backward/. (Note that it is better to -include them via "" or "" than -to search the subdirectory itself via a "-I" directive. - diff --git a/libstdc++-v3/doc/html/17_intro/TODO b/libstdc++-v3/doc/html/17_intro/TODO deleted file mode 100644 index a0a257c4876a..000000000000 --- a/libstdc++-v3/doc/html/17_intro/TODO +++ /dev/null @@ -1,164 +0,0 @@ -std::allocator - - - persistent allocator - - - shared memory allocator (use or link to boost::shmem::allocator) - -std::string - - - document __gnu_cxx::__versa_string, add new policies - (Policy-based design incorporating COW - vs. deep copy issues, MT scalability - See Andrei Alexandrescu, June 2001, C/C++ Users Journal - "Generic: A Policy-Based basic_string Implementation" - http://www.cuj.com/documents/s=7994/cujcexp1906alexandr/) - - - operator!= and utility/rel_ops operators need to be made safe with - string and vector iterator classes. basic_string::reverse_iterator may - be implemented incorrectly, or need things like - operator==(__normal_iterator, const char*&), and swap(vector) - - - 'do the right thing' ctor fixing needs to be done for string. This - is still subject to some debate on the library issues list, so I - suggest punting till the dust clears. - - - fix template members of basic_string<> to overload iterators and - non-iterators properly. (This is the infamous hack as in vector<> etc - 23.1.1 para 10.) - -std::locale - - - implement __convert_to_v and __convert_from_v without "C" library - functions and and LANG environment variable dependencies. - - - use localedata to implement generic named (non-MT-safe) locales? - Figure out a way to use ICU data, like libjava? Re-package and use - the glibc localedata, even if we aren't on linux? Need a generic - locale model that does something besides the "C" locale. - - - make locale::classic() separate from named locale code. This will - improve the static linkage situation, but will require new - initialization code. In particular, we need lazy-initialization of - locale::classic(), and maybe the has_facet/use_facet functions for all - the required facets. The end goal is a self-contained - locale_init.cc, or one with transitive closure without the locale - instantiations (locale-inst.cc) or the named locale bits - (localename.cc). - - - Jerry(?)/Paolo(?) work on __float_to_char. - - - minimize ctype convertion in data facets, see numpunct/num_put/num_get - -std::basic_filebuf, 27_io - - - wfilebuf, get variable-encoding working and tested, including - positioning and seeking. (I think this may be done now) - - - wfilebuf testsuite (getting there...) - - - look ahead for unbuffered io, so know when multiple putc's can be - coalesced. - - - unlocked __basic_file + new mutext class - - - optimized the sentries for istream/ostream - - - v2 vs. v3 speed - - - add optimization hooks (esp. whitespace eating) to streambuf - - add _M_begin() and _M_end() to streambuf - - add algorithm specializations for [io]streambuf_iterator (copy find etc.) - -testsuite - - - valgrind hooks into make check so can tell memory leakage - Some commentary on the valgrind users list - - - add hooks for qmtest, pychart, other for visual diffs - - - automatic testing of interactive tests - - - diffing generated output files - - - provide testsuites for numerics. - - - make check-abi needs to have full symbol checking. Scope the LSB - testsuite, see what's going on with the typeinfo etc. bits. - - - try to do a better job of ABI testing, with instantiations of all - standard-specified types checked, not just exported symbols. - -g++/binutils - - - compression for wide versions of basic types, not just narrow - -threads - - - create MT abstraction layer for atomicity to pthreads. - - - solution for threads + C++. - -other/random - -- relocations, work on getting these down - -- issues with __builtin_memcpy and std::copy from Jerry Quinn - http://gcc.gnu.org/ml/libstdc++/2003-02/msg00056.html - http://gcc.gnu.org/ml/libstdc++/2003-02/msg00302.html - http://gcc.gnu.org/ml/gcc/2003-10/msg01305.html - -- fix dependency tracking for includes (.h, .tcc) during build process. - -- coordinate with "C" library people the "C" compatibility headers. - -- Think about naming all member data and member functions consistently - as per - funtions: _M_verb_adverb - data: _M_noun_adjective - -- A C++STYLE guide that deals with nested namespaces, and that -everybody can live with. - -- exception specifications need to be reviewed for all parts of the -library support and utility areas, particularly . Part of this is -a standards issue, where the 27_io standard is really in an odd -spot. Do the work to make this consistent. - -- C-related issues WRT to io and filepos, mbstate_t. Seeking in wide -streams. May need to define operators for mbstate_t so that -'mbstate_t& == mbstate_t' is something that can be done. - -- scoping/linking issues WRT to C structs need to be worked out. See -Nathan's commentary on cantrip, http://www.cantrip.org/cheaders.html - -- auto_ptr: seems to be some disagreement on what is -standards-conformant behavior, specially on conversion operators. - -- list::assignment operator needs const_cast - -- a cleaner division between pointers-to-value_type and true iterators -needs to be drawn throughout the entire STL implementation. - -- priority_queue conversions may be non-conformant - -- Protect valarray::result_type (not Standard) and make it work with - the various helper classes. - -- Make sure `valarray & == _Expr<_BinClos,bool>' - is defined - -- All of the Library working group closed issues need to be -addressed. Some of them proposed resolutions are already in the v-3 -sources, with macro-guards. Also, same with the TR. - -- need to think about doing a .texi or DocBook manual, instead of all -these HTML pages. In addition, it would be nice to have a full manual, -instead of a lot of ad-hoc pages. Weaknesses include numerics, locale, -and io. - -- add FAQ entries -- improve the install instructions - -- add HOWTO entries - -- do more doxygen manpages - diff --git a/libstdc++-v3/doc/html/17_intro/abi.html b/libstdc++-v3/doc/html/17_intro/abi.html deleted file mode 100644 index c27de61515c7..000000000000 --- a/libstdc++-v3/doc/html/17_intro/abi.html +++ /dev/null @@ -1,991 +0,0 @@ - - - - - - - - - - Standard C++ Library ABI - - - - - - -

C++ Standard Library ABI

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/abi.html. -

- -

- To the libstdc++ homepage. -

- - -
-

- The C++ interface -

- -

C++ applications often dependent on specific language support -routines, say for throwing exceptions, or catching exceptions, and -perhaps also dependent on features in the C++ Standard Library. -

- -

The C++ Standard Library has many include files, types defined in -those include files, specific named functions, and other behavior. The -text of these behaviors, as written in source include files, is called -the Application Programing Interface, or API. -

- -

Furthermore, C++ source that is compiled into object files is - transformed by the compiler: it arranges objects with specific - alignment and in a particular layout, mangling names according to a - well-defined algorithm, has specific arrangements for the support of - virtual functions, etc. These details are defined as the compiler - Application Binary Interface, or ABI. The GNU C++ compiler uses an - industry-standard C++ ABI starting with version 3. Details can be - found in the - ABI specification. -

- -

- The GNU C++ compiler, g++, has a compiler command line option to - switch between various different C++ ABIs. This explicit version - switch is the flag -fabi-version. In addition, some - g++ command line options may change the ABI as a side-effect of - use. Such flags include -fpack-struct and - -fno-exceptions, but include others: see the complete - list in the GCC manual under the heading Options - for Code Generation Conventions. -

- -

The configure options used when building a specific libstdc++ -version may also impact the resulting library ABI. The available -configure options, and their impact on the library ABI, are documented - -here. -

- -

Putting all of these ideas together results in the C++ Standard -library ABI, which is the compilation of a given library API by a -given compiler ABI. In a nutshell: -

- - library API + compiler ABI = library ABI - -

- The library ABI is mostly of interest for end-users who have - unresolved symbols and are linking dynamically to the C++ Standard - library, and who thus must be careful to compile their application - with a compiler that is compatible with the available C++ Standard - library binary. In this case, compatible is defined with the equation - above: given an application compiled with a given compiler ABI and - library API, it will work correctly with a Standard C++ Library - created with the same constraints. -

- -

- To use a specific version of the C++ ABI, one must use a - corresponding GNU C++ toolchain (Ie, g++ and libstdc++) that - implements the C++ ABI in question. -

- -

- Versioning -

- -

The C++ interface has evolved throughout the history of the GNU -C++ toolchain. With each release, various details have been changed so -as to give distinct versions to the C++ interface. -

- -
- Goals of versioning -
- -

Extending existing, stable ABIs. Versioning gives subsequent stable -releases series libraries the ability to add new symbols and add -functionality, all the while retaining backwards compatibility with -the previous releases in the series. Note: the reverse is not true. It -is not possible to take binaries linked with the latest version of a -release series (if symbols have been added) and expect the initial -release of the series to remain link compatible. -

- -

Allows multiple, incompatible ABIs to coexist at the same time. -

- -

-

- -
- Version History -
-

- How can this complexity be managed? What does C++ versioning mean? - Because library and compiler changes often make binaries compiled - with one version of the GNU tools incompatible with binaries - compiled with other (either newer or older) versions of the same GNU - tools, specific techniques are used to make managing this complexity - easier. -

- -

- The following techniques are used: -

- -
    - -

  • Release versioning on the libgcc_s.so binary. This is -implemented via file names and the ELF DT_SONAME mechanism (at least -on ELF systems).

    - -

    It is versioned as follows: -

    -
      -
    • gcc-3.0.0: libgcc_s.so.1
      • -
    • gcc-3.0.1: libgcc_s.so.1
      • -
    • gcc-3.0.2: libgcc_s.so.1
      • -
    • gcc-3.0.3: libgcc_s.so.1
      • -
    • gcc-3.0.4: libgcc_s.so.1
      • -
    • gcc-3.1.0: libgcc_s.so.1
      • -
    • gcc-3.1.1: libgcc_s.so.1
      • -
    • gcc-3.2.0: libgcc_s.so.1
      • -
    • gcc-3.2.1: libgcc_s.so.1
      • -
    • gcc-3.2.2: libgcc_s.so.1
      • -
    • gcc-3.2.3: libgcc_s.so.1
      • -
    • gcc-3.3.0: libgcc_s.so.1
      • -
    • gcc-3.3.1: libgcc_s.so.1
      • -
    • gcc-3.3.2: libgcc_s.so.1
      • -
    • gcc-3.3.3: libgcc_s.so.1
      • -
    • gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: on m68k-linux and - hppa-linux this is either libgcc_s.so.1 (when configuring - --with-sjlj-exceptions) or libgcc_s.so.2. For all - others, this is libgcc_s.so.1.
    -

    -
    • - -
  • Symbol versioning on the libgcc_s.so binary. -

    mapfile: gcc/libgcc-std.ver

    - -

    It is versioned with the following labels and version - definitions, where the version definition is the maximum for a - particular release. Labels are cumulative. If a particular release - is not listed, it has the same version labels as the preceeding - release.

    -
      -
    • gcc-3.0.0: GCC_3.0
      • -
    • gcc-3.3.0: GCC_3.3
      • -
    • gcc-3.3.1: GCC_3.3.1
      • -
    • gcc-3.3.2: GCC_3.3.2
      • -
    • gcc-3.3.4: GCC_3.3.4
      • -
    • gcc-3.4.0: GCC_3.4
      • -
    • gcc-3.4.2: GCC_3.4.2
      • -
    • gcc-3.4.4: GCC_3.4.4
      • -
    • gcc-4.0.0: GCC_4.0.0
      • -
    • gcc-4.1.0: GCC_4.1.0
      • -
    • gcc-4.2.0: GCC_4.2.0
      • -
    -

    -
    • - -
  • Release versioning on the libstdc++.so binary, implemented in the same was as the libgcc_s.so binary, above. - -

    It is versioned as follows: -

    -
      -
    • gcc-3.0.0: libstdc++.so.3.0.0
      • -
    • gcc-3.0.1: libstdc++.so.3.0.1
      • -
    • gcc-3.0.2: libstdc++.so.3.0.2
      • -
    • gcc-3.0.3: libstdc++.so.3.0.2 (Error should be libstdc++.so.3.0.3)
      • -
    • gcc-3.0.4: libstdc++.so.3.0.4
      • -
    • gcc-3.1.0: libstdc++.so.4.0.0
      • -
    • gcc-3.1.1: libstdc++.so.4.0.1
      • -
    • gcc-3.2.0: libstdc++.so.5.0.0
      • -
    • gcc-3.2.1: libstdc++.so.5.0.1
      • -
    • gcc-3.2.2: libstdc++.so.5.0.2
      • -
    • gcc-3.2.3: libstdc++.so.5.0.3 (Not strictly required)
      • -
    • gcc-3.3.0: libstdc++.so.5.0.4
      • -
    • gcc-3.3.1: libstdc++.so.5.0.5
      • -
    • gcc-3.3.2: libstdc++.so.5.0.5
      • -
    • gcc-3.3.3: libstdc++.so.5.0.5
      • -
    • gcc-3.4.0: libstdc++.so.6.0.0
      • -
    • gcc-3.4.1: libstdc++.so.6.0.1
      • -
    • gcc-3.4.2: libstdc++.so.6.0.2
      • -
    • gcc-3.4.3: libstdc++.so.6.0.3
      • -
    • gcc-3.4.4: libstdc++.so.6.0.3
      • -
    • gcc-3.4.5: libstdc++.so.6.0.3
      • -
    • gcc-3.4.6: libstdc++.so.6.0.3
      • -
    • gcc-4.0.0: libstdc++.so.6.0.4
      • -
    • gcc-4.0.1: libstdc++.so.6.0.5
      • -
    • gcc-4.0.2: libstdc++.so.6.0.6
      • -
    • gcc-4.0.3: libstdc++.so.6.0.7
      • -
    • gcc-4.1.0: libstdc++.so.6.0.7
      • -
    • gcc-4.1.1: libstdc++.so.6.0.8
      • -
    • gcc-4.1.2: libstdc++.so.6.0.8
      • -
    • gcc-4.2.0: libstdc++.so.6.0.9
      • -
    -

    -
    • - -
  • Symbol versioning on the libstdc++.so binary. - -

    mapfile: libstdc++/config/linker-map.gnu

    -

    It is versioned with the following labels and version - definitions, where the version definition is the maximum for a - particular release. Note, only symbol which are newly introduced - will use the maximum version definition. Thus, for release series - with the same label, but incremented version definitions, the later - release has both versions. (An example of this would be the - gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and - GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0 - release.) If a particular release is not listed, it has the same - version labels as the preceeding release. -

    -
      -
    • gcc-3.0.0: (Error, not versioned)
      • -
    • gcc-3.0.1: (Error, not versioned)
      • -
    • gcc-3.0.2: (Error, not versioned)
      • -
    • gcc-3.0.3: (Error, not versioned)
      • -
    • gcc-3.0.4: (Error, not versioned)
      • -
    • gcc-3.1.0: GLIBCPP_3.1, CXXABI_1
      • -
    • gcc-3.1.1: GLIBCPP_3.1, CXXABI_1
      • -
    • gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2
      • -
    • gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2
      • -
    • gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2
      • -
    • gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2
      • -
    • gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1
      • -
    • gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1
      • -
    • gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1
      • -
    • gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1
      • -
    • gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3
      • -
    • gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3
      • -
    • gcc-3.4.2: GLIBCXX_3.4.2
      • -
    • gcc-3.4.3: GLIBCXX_3.4.3
      • -
    • gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1
      • -
    • gcc-4.0.1: GLIBCXX_3.4.5
      • -
    • gcc-4.0.2: GLIBCXX_3.4.6
      • -
    • gcc-4.0.3: GLIBCXX_3.4.7
      • -
    • gcc-4.1.1: GLIBCXX_3.4.8
      • -
    • gcc-4.2.0: GLIBCXX_3.4.9
      • -
    -

    -
    • - -
  • -

    Incremental bumping of a compiler pre-defined macro, - __GXX_ABI_VERSION. This macro is defined as the version of the - compiler v3 ABI, with g++ 3.0.x being version 100. This macro will - be automatically defined whenever g++ is used (the curious can - test this by invoking g++ with the '-v' flag.) -

    - -

    - This macro was defined in the file "lang-specs.h" in the gcc/cp directory. - Later versions defined it in "c-common.c" in the gcc directory, and from - G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the - '-fabi-version' command line option. -

    - -

    - It is versioned as follows, where 'n' is given by '-fabi-version=n': -

    -
      -
    • gcc-3.0.x: 100
      • -
    • gcc-3.1.x: 100 (Error, should be 101)
      • -
    • gcc-3.2.x: 102
      • -
    • gcc-3.3.x: 102
      • -
    • gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 102 (when n=1)
      • -
    • gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 1000 + n (when n>1)
      • -
    • gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 999999 (when n=0)
      • -
    -

    -
    • - -
  • -

    Changes to the default compiler option for - -fabi-version. -

    -

    - It is versioned as follows: -

    -
      -
    • gcc-3.0.x: (Error, not versioned)
      • -
    • gcc-3.1.x: (Error, not versioned)
      • -
    • gcc-3.2.x: -fabi-version=1
      • -
    • gcc-3.3.x: -fabi-version=1
      • -
    • gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: -fabi-version=2
      • -
    -

    -
    • - -
  • -

    Incremental bumping of a library pre-defined macro. For releases - before 3.4.0, the macro is __GLIBCPP__. For later releases, it's - __GLIBCXX__. (The libstdc++ project generously changed from CPP to - CXX throughout its source to allow the "C" pre-processor the CPP - macro namespace.) These macros are defined as the date the library - was released, in compressed ISO date format, as an unsigned long. -

    - -

    - This macro is defined in the file "c++config" in the - "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was - changed every night by an automated script. Since gcc-4.1.0, it is - the same value as gcc/DATESTAMP.) -

    -

    - It is versioned as follows: -

    -
      -
    • gcc-3.0.0: 20010615
      • -
    • gcc-3.0.1: 20010819
      • -
    • gcc-3.0.2: 20011023
      • -
    • gcc-3.0.3: 20011220
      • -
    • gcc-3.0.4: 20020220
      • -
    • gcc-3.1.0: 20020514
      • -
    • gcc-3.1.1: 20020725
      • -
    • gcc-3.2.0: 20020814
      • -
    • gcc-3.2.1: 20021119
      • -
    • gcc-3.2.2: 20030205
      • -
    • gcc-3.2.3: 20030422
      • -
    • gcc-3.3.0: 20030513
      • -
    • gcc-3.3.1: 20030804
      • -
    • gcc-3.3.2: 20031016
      • -
    • gcc-3.3.3: 20040214
      • -
    • gcc-3.4.0: 20040419
      • -
    • gcc-3.4.1: 20040701
      • -
    • gcc-3.4.2: 20040906
      • -
    • gcc-3.4.3: 20041105
      • -
    • gcc-3.4.4: 20050519
      • -
    • gcc-3.4.5: 20051201
      • -
    • gcc-3.4.6: 20060306
      • -
    • gcc-4.0.0: 20050421
      • -
    • gcc-4.0.1: 20050707
      • -
    • gcc-4.0.2: 20050921
      • -
    • gcc-4.0.3: 20060309
      • -
    • gcc-4.1.0: 20060228
      • -
    • gcc-4.1.1: 20060524
      • -
    • gcc-4.1.2: 20070214
      • -
    • gcc-4.2.0: 20070514
      • -
    -

    -
    • - -
  • -

    - Incremental bumping of a library pre-defined macro, - _GLIBCPP_VERSION. This macro is defined as the released version of - the library, as a string literal. This is only implemented in - gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it - is called _GLIBCXX_VERSION). -

    - -

    - This macro is defined in the file "c++config" in the - "libstdc++/include/bits" directory and is generated - automatically by autoconf as part of the configure-time generation - of config.h. -

    - -

    - It is versioned as follows: -

    -
      -
    • gcc-3.0.0: "3.0.0"
      • -
    • gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")
      • -
    • gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")
      • -
    • gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")
      • -
    • gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")
      • -
    • gcc-3.1.0: "3.1.0"
      • -
    • gcc-3.1.1: "3.1.1"
      • -
    • gcc-3.2.0: "3.2"
      • -
    • gcc-3.2.1: "3.2.1"
      • -
    • gcc-3.2.2: "3.2.2"
      • -
    • gcc-3.2.3: "3.2.3"
      • -
    • gcc-3.3.0: "3.3"
      • -
    • gcc-3.3.1: "3.3.1"
      • -
    • gcc-3.3.2: "3.3.2"
      • -
    • gcc-3.3.3: "3.3.3"
      • -
    • gcc-3.4.x: "version-unused"
      • -
    • gcc-4.0.x: "version-unused"
      • -
    • gcc-4.1.x: "version-unused"
      • -
    • gcc-4.2.x: "version-unused"
      • -
    -

    -
    • - -
  • -

    - Matching each specific C++ compiler release to a specific set of - C++ include files. This is only implemented in gcc-3.1.1 releases - and higher. -

    -

    - All C++ includes are installed in include/c++, then nest in a - directory hierarchy corresponding to the C++ compiler's released - version. This version corresponds to the variable "gcc_version" in - "libstdc++/acinclude.m4," and more details can be found in that - file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0). -

    -

    - C++ includes are versioned as follows: -

    -
      -
    • gcc-3.0.0: include/g++-v3
      • -
    • gcc-3.0.1: include/g++-v3
      • -
    • gcc-3.0.2: include/g++-v3
      • -
    • gcc-3.0.3: include/g++-v3
      • -
    • gcc-3.0.4: include/g++-v3
      • -
    • gcc-3.1.0: include/g++-v3
      • -
    • gcc-3.1.1: include/c++/3.1.1
      • -
    • gcc-3.2.0: include/c++/3.2
      • -
    • gcc-3.2.1: include/c++/3.2.1
      • -
    • gcc-3.2.2: include/c++/3.2.2
      • -
    • gcc-3.2.3: include/c++/3.2.3
      • -
    • gcc-3.3.0: include/c++/3.3
      • -
    • gcc-3.3.1: include/c++/3.3.1
      • -
    • gcc-3.3.2: include/c++/3.3.2
      • -
    • gcc-3.3.3: include/c++/3.3.3
      • -
    • gcc-3.4.0: include/c++/3.4.0
      • -
    • gcc-3.4.1: include/c++/3.4.1
      • -
    • gcc-3.4.2: include/c++/3.4.2
      • -
    • gcc-3.4.3: include/c++/3.4.3
      • -
    • gcc-3.4.4: include/c++/3.4.4
      • -
    • gcc-3.4.5: include/c++/3.4.5
      • -
    • gcc-3.4.6: include/c++/3.4.6
      • -
    • gcc-4.0.0: include/c++/4.0.0
      • -
    • gcc-4.0.1: include/c++/4.0.1
      • -
    • gcc-4.0.2: include/c++/4.0.2
      • -
    • gcc-4.0.3: include/c++/4.0.3
      • -
    • gcc-4.1.0: include/c++/4.1.0
      • -
    • gcc-4.1.1: include/c++/4.1.1
      • -
    • gcc-4.1.2: include/c++/4.1.2
      • -
    • gcc-4.2.0: include/c++/4.2.0
      • -
    -

    -
    • -
-

- Taken together, these techniques can accurately specify interface - and implementation changes in the GNU C++ tools themselves. Used - properly, they allow both the GNU C++ tools implementation, and - programs using them, an evolving yet controlled development that - maintains backward compatibility. -

- - - -
- Minimum requirements for a versioned ABI -
-

- Minimum environment that supports a versioned ABI: A supported - dynamic linker, a GNU linker of sufficient vintage to understand - demangled C++ name globbing (ld), a shared executable compiled with - g++, and shared libraries (libgcc_s, libstdc++) compiled by a - compiler (g++) with a compatible ABI. Phew. -

- -

- On top of all that, an additional constraint: libstdc++ did not - attempt to version symbols (or age gracefully, really) until version - 3.1.0. -

- -

- Most modern Linux and BSD versions, particularly ones using - gcc-3.1.x tools and more recent vintages, will meet the requirements above. -

- - -
- What configure options impact symbol versioning? -
-

- It turns out that most of the configure options that change default - behavior will impact the mangled names of exported symbols, and thus - impact versioning and compatibility. -

- -

- For more information on configure options, including ABI impacts, see: - http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html -

- -

- There is one flag that explicitly deals with symbol versioning: - --enable-symvers. -

- -

- In particular, libstdc++/acinclude.m4 has a macro called - GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument passed - in via --enable-symvers=foo). At that point, the macro attempts to - make sure that all the requirement for symbol versioning are in - place. For more information, please consult acinclude.m4. -

- - -
- How to tell if symbol versioning is, indeed, active? -
-

- When the GNU C++ library is being built with symbol versioning on, - you should see the following at configure time for libstdc++: -

- - - checking versioning on shared library symbols... gnu - -

- If you don't see this line in the configure output, or if this line - appears but the last word is 'no', then you are out of luck. -

- -

- If the compiler is pre-installed, a quick way to test is to compile - the following (or any) simple C++ file and link it to the shared - libstdc++ library: -

- -
-#include <iostream>
-
-int main()
-{ std::cout << "hello" << std::endl; return 0; }
-
-%g++ hello.cc -o hello.out
-
-%ldd hello.out
-        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
-
-%nm hello.out
-
- -

-If you see symbols in the resulting output with "GLIBCXX_3" as part -of the name, then the executable is versioned. Here's an example: -

- - U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4 - -

- Library allowed ABI changes -

-

-The following will cause the library minor version number to -increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". -

-
    -
  • adding an exported global or static data member
    • -
  • adding an exported function, static or non-virtual member function
    • -
  • adding an exported symbol or symbols by additional instantiations
    • -
-

-

-

-Other allowed changes are possible. -

- - -

- Library disallowed ABI changes -

- -

-The following non-exhaustive list will cause the library major version -number to increase, say from "libstdc++.so.3.0.4" to -"libstdc++.so.4.0.0". -

-
    -
  • changes in the gcc/g++ compiler ABI
    • -
  • changing size of an exported symbol
    • -
  • changing alignment of an exported symbol
    • -
  • changing the layout of an exported symbol
    • -
  • changing mangling on an exported symbol
    • -
  • deleting an exported symbol
    • -
  • changing the inheritance properties of a type by adding or removing - base classes
    • -
  • - changing the size, alignment, or layout of types - specified in the C++ standard. These may not necessarily be - instantiated or otherwise exported in the library binary, and - include all the required locale facets, as well as things like - std::basic_streambuf, et al. -
    • - -
  • adding an explicit copy constructor or destructor to a -class that would otherwise have implicit versions. This will change -the way the compiler deals with this class in by-value return -statements or parameters: instead of being passing instances of this -class in registers, the compiler will be forced to use memory. See this part - of the C++ ABI documentation for further details. -
    • - -
- -

- Library implementation strategy

- -
    -
  • Separation of interface and implementation -

    This is accomplished by two techniques that separate the API from -the ABI: forcing undefined references to link against a library binary -for definitions. -

    - -
    -
    Include files have declarations, source files have defines
    - -
    For non-templatized types, such as much of class - locale, the appropriate standard C++ include, say - locale, can contain full declarations, while various - source files (say locale.cc, locale_init.cc, - localename.cc) contain definitions.
    - -
    Extern template on required types
    - -
    For parts of the standard that have an explicit list of required - instantiations, the GNU extension syntax extern template - can be used to control where template definitions - reside. By marking required instantiations as extern - template in include files, and providing explicit - instantiations in the appropriate instantiation files, non-inlined - template functions can be versioned. This technique is mostly used - on parts of the standard that require char and - wchar_t instantiations, and includes - basic_string, the locale facets, and the types in - iostreams.
    - -
    -

    In addition, these techniques have the additional benefit that - they reduce binary size, which can increase runtime performance. -

    -
    • - -
  • Namespaces linking symbol definitions to export mapfiles - -

    All symbols in the shared library binary are processed by a linker -script at build time that either allows or disallows external -linkage. Because of this, some symbols, regardless of normal C/C++ -linkage, are not visible. Symbols that are internal have several -appealing characteristics: by not exporting the symbols, there are no -relocations when the shared library is started and thus this makes for -faster runtime loading performance by the underlying dynamic loading -mechanism. In addition, they have the possibility of changing without -impacting ABI compatibility. -

    - -

    The following namespaces are transformed by the mapfile:

    - -
    -
    namespace std
    -
    Defaults to exporting all symbols in label -GLIBCXX that do not begin with an underscore, ie -__test_func would not be exported by default. Select -exceptional symbols are allowed to be visible.
    - -
    namespace __gnu_cxx
    -
    Defaults to not exporting any symbols in label -GLIBCXX, select items are allowed to be visible.
    - -
    namespace __gnu_internal
    -
    Defaults to not exported, no items are allowed to be visible.
    - -
    namespace __cxxabiv1, aliased to namespace abi
    -
    Defaults to not exporting any symbols in label -CXXABI, select items are allowed to be visible.
    -
    -

    -

    -
    • - -
  • Freezing the API -

    Disallowed changes, as above, are not made on a stable release -branch. Enforcement tends to be less strict with GNU extensions that -standard includes.

    -
    • -
- -

- Testing ABI changes -

- -

-Testing for GNU C++ ABI changes is composed of two distinct areas: -testing the C++ compiler (g++) for compiler changes, and testing the -C++ library (libstdc++) for library changes. -

- -

-Testing the C++ compiler ABI can be done various ways. -

- -

-One. -Intel ABI checker. More information can be obtained -here. -

- -

-Two. -The second is yet unreleased, but has been announced on the gcc -mailing list. It is yet unspecified if these tools will be freely -available, and able to be included in a GNU project. Please contact -Mark Mitchell (mark@codesourcery.com) for more details, and current -status. -

- -

-Three. -Involves using the vlad.consistency test framework. This has also been -discussed on the gcc mailing lists. -

- -

-Testing the C++ library ABI can also be done various ways. -

- -

-One. -(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, -one with a new compiler and an old library, and the other with an old -compiler and a new library, and look for testsuite regressions) -

- -

-Details on how to set this kind of test up can be found here: -http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html -

- -

-Two. -Use the 'make check-abi' rule in the libstdc++ Makefile. -

- -

-This is a proactive check the library ABI. Currently, exported symbol -names that are either weak or defined are checked against a last known -good baseline. Currently, this baseline is keyed off of 3.4.0 -binaries, as this was the last time the .so number was incremented. In -addition, all exported names are demangled, and the exported objects -are checked to make sure they are the same size as the same object in -the baseline. - -Notice that each baseline is relative to a default -configured library and compiler: in particular, if options such as ---enable-clocale, or --with-cpu, in case of multilibs, are used at -configure time, the check may fail, either because of substantive -differences or because of limitations of the current checking -machinery. -

- -

-This dataset is insufficient, yet a start. Also needed is a -comprehensive check for all user-visible types part of the standard -library for sizeof() and alignof() changes. -

- -

-Verifying compatible layouts of objects is not even attempted. It -should be possible to use sizeof, alignof, and offsetof to compute -offsets for each structure and type in the standard library, saving to -another datafile. Then, compute this in a similar way for new -binaries, and look for differences. -

- -

-Another approach might be to use the -fdump-class-hierarchy flag to -get information. However, currently this approach gives insufficient -data for use in library testing, as class data members, their offsets, -and other detailed data is not displayed with this flag. -(See g++/7470 on how this was used to find bugs.) -

- -

-Perhaps there are other C++ ABI checkers. If so, please notify -us. We'd like to know about them! -

- -

- Testing Multi-ABI binaries -

- -

-A "C" application, dynamically linked to two shared libraries, liba, -libb. The dependent library liba is C++ shared library compiled with -gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library -libb is a C++ shared library compiled with gcc-3.4.x, and also uses io, -exceptions, locale, etc. -

- -

As above, libone is constructed as follows:

-
-%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
-
-%$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0
-
-%ln -s libone.so.1.0.0 libone.so
-
-%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
-
-%ar cru libone.a a.o 
-
- -

And, libtwo is constructed as follows:

- -
-%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
-
-%$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0
-
-%ln -s libtwo.so.1.0.0 libtwo.so
-
-%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
-
-%ar cru libtwo.a b.o 
-
- -

...with the resulting libraries looking like

-
-%ldd libone.so.1.0.0
-        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
-
-%ldd libtwo.so.1.0.0
-        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
-
-
- -

Then, the "C" compiler is used to compile a source file that uses -functions from each library.

-
-gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
-
- -

-Which gives the expected: -

-
-%ldd a.out
-        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
-        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
-
- -

-This resulting binary, when executed, will be able to safely use code -from both liba, and the dependent libstdc++.so.6, and libb, with the -dependent libstdc++.so.5. -

- - -

- Outstanding Issues -

- -

Some features in the C++ language make versioning especially -difficult. In particular, compiler generated constructs such as -implicit instantiations for templates, typeinfo information, and -virtual tables all may cause ABI leakage across shared library -boundaries. Because of this, mixing C++ ABI's is not recommended at -this time. -

- -

For more background on this issue, see these bugzilla entries:

- -

-24660: versioning weak symbols in libstdc++ -

- -

-19664: libstdc++ headers should have pop/push of the visibility around the declarations -

- -

- Bibliography / Further Reading -

- -

-ABIcheck, a vague idea of checking ABI compatibility -
-http://abicheck.sourceforge.net/ -

- -

-C++ ABI reference -
-http://www.codesourcery.com/cxx-abi/ -

- -

-Intel ABI documentation, "Intel® Compilers for Linux* -Compatibility with the GNU Compilers" -
-http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm -

- -

-Sun Solaris 2.9 docs -
-Linker and Libraries Guide (document 816-1386) -
-C++ Migration Guide (document 816-2459) -
-http://docs.sun.com/db/prod/solaris.9 -
-http://docs.sun.com/?p=/doc/816-1386&a=load -

- -

-Ulrich Drepper, "ELF Symbol Versioning" -
-http://people.redhat.com/drepper/symbol-versioning -

- -

-C++ ABI for the ARM Architecture -
-http://www.arm.com/miscPDFs/8033.pdf -

- -

-Benjamin Kosnik, ISO C++ J16/06-0046 -
-Dynamic Shared Objects: Survey and Issues -

- -

-Benjamin Kosnik, ISO C++ J16/06-0083 -
-Versioning With Namespaces -

- - - - diff --git a/libstdc++-v3/doc/html/17_intro/api.html b/libstdc++-v3/doc/html/17_intro/api.html deleted file mode 100644 index 1d1e36d90d2e..000000000000 --- a/libstdc++-v3/doc/html/17_intro/api.html +++ /dev/null @@ -1,290 +0,0 @@ - - - - - - - - - - API Evolution and Deprecation History - - - - - - -

API Evolution and Deprecation History

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/api.html. -

- -

- To the libstdc++ homepage. -

- - - -
-

- API Evolution, Deprecation, and History of User Visible Changes -

- -

A list of user-visible changes, by release version. -

- -

- 3.0 -

- -

-Extensions moved to include/ext. -

- -

-Include files from the SGI/HP sources that pre-date the ISO standard -are added. These files are placed into -the include/backward directory and a deprecated warning -is added that notifies on inclusion (-Wno-deprecated -deactivates the warning.) -

- -

Deprecated include <backward/strstream> added.

- -

Removal of include <builtinbuf.h>, <indstream.h>, <parsestream.h>, <PlotFile.h>, <SFile.h>, <stdiostream.h>, and <stream.h>.

- - -

- 3.1 -

- -

-Extensions from SGI/HP moved from namespace std -to namespace __gnu_cxx. As part of this, the following -new includes are -added: <ext/algorithm>, <ext/functional>, <ext/iterator>, <ext/memory>, and <ext/numeric>. -

- -

-Extensions to basic_filebuf introduced: __gnu_cxx::enc_filebuf, and __gnu_cxx::stdio_filebuf. -

- -

-Extensions to tree data structures added in <ext/rb_tree>. -

- -

-Removal of <ext/tree>, moved to <backward/tree.h>. -

- - -

- 3.2 -

-

Symbol versioning introduced for shared library.

- -

Removal of include <backward/strstream.h>.

- -

- 3.3 -

-

Allocator changes. Change __malloc_alloc to malloc_allocator and __new_alloc to new_allocator.

- -

Error handling in iostreams cleaned up, made consistent.

- - -

- 3.4 -

-

-Large file support. -

- -

Extensions for generic characters and char_traits added in <ext/pod_char_traits.h>. -

- -

-Support for wchar_t specializations of basic_filebuf enhanced to support UTF-8 and Unicode, depending on host. More hosts support basic wchar_t functionality. -

- -

-Support for char_traits beyond builtin types. -

- -

-Conformant allocator class and usage in containers. As -part of this, the following extensions are -added: <ext/bitmap_allocator.h>, <ext/debug_allocator.h>, <ext/mt_allocator.h>, <ext/malloc_allocator.h>,<ext/new_allocator.h>, <ext/pool_allocator.h>. -

- - -

-Debug mode first appears. -

- -

-PCH support. -

- -

-Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_. -

- -

-Extension <ext/stdio_sync_filebuf.h> added. -

- -

-Extension <ext/demangle.h> added. -

- - -

- 4.0 -

-

-TR1 features first appear. -

- -

-Extension allocator <ext/array_allocator.h> added. -

- -

-Extension codecvt specializations moved to <ext/codecvt_specializations.h>. -

- -

-Removal of <ext/demangle.h>. -

- - -

- 4.1 -

- -

-Removal of <cassert> from all standard headers: now has to be explicitly included for std::assert calls. -

- -

Extensions for policy-based data structures first added. New includes, -types, namespace pb_assoc. -

- - - -

Extensions for typelists added in <ext/typelist.h>. -

- -

Extension for policy-based basic_string first added: __gnu_cxx::__versa_string in <ext/vstring.h>. -

- -

- 4.2 -

- -

Default visibility attributes applied to namespace std. Support for -fvisibility. -

- -

TR1 <random>, <complex>, and C compatibility headers added.

- -

Extensions for concurrent programming consolidated -into <ext/concurrence.h> and <ext/atomicity.h>, -including change of namespace to __gnu_cxx in some -cases. Added types -include _Lock_policy, __concurrence_lock_error, __concurrence_unlock_error, __mutex, __scoped_lock.

- -

Extensions for type traits consolidated -into <ext/type_traits.h>. Additional traits are added -(__conditional_type, __enable_if, others.) -

- -

Extensions for policy-based data structures revised. New includes, -types, namespace moved to __pb_ds. -

- -

Extensions for debug mode modified: now nested in namespace -std::__debug and extensions in namespace -__gnu_cxx::__debug.

- -

Extensions added: <ext/typelist.h> -and <ext/throw_allocator.h>. -

- -

- 4.3 -

- -

-C++0X features first appear. -

- -

TR1 <regex> and <cmath>'s mathematical special function added.

- -

-Backward include edit. -

-
    -
  • Removed: <algobase.h> <algo.h> <alloc.h> <bvector.h> <complex.h> -defalloc.h> <deque.h> <fstream.h> <function.h> <hash_map.h> <hash_set.h> -hashtable.h> <heap.h> <iomanip.h> <iostream.h> <istream.h> <iterator.h> -list.h> <map.h> <multimap.h> <multiset.h> <new.h> <ostream.h> <pair.h> <queue.h> <rope.h> <set.h> <slist.h> <stack.h> <streambuf.h> <stream.h> <tempbuf.h> -<tree.h> <vector.h> -
    • -
  • Added: <hash_map> and <hash_set>
    • -
  • Added in C++0x: <auto_ptr.h> and <binders.h>
    • -
- -

-Header dependency streamlining. -

- -
    -
  • <algorithm> no longer includes <climits>, <cstring>, or <iosfwd>
    • -
  • <bitset> no longer includes <istream> or <ostream>, adds <iosfwd>
    • -
  • <functional> no longer includes <cstddef>
    • -
  • <iomanip> no longer includes <istream>, <istream>, or <functional>, adds <ioswd>
    • -
  • <numeric> no longer includes <iterator>
    • -
  • <string> no longer includes <algorithm> or <memory>
    • - -
  • <valarray> no longer includes <numeric> or <cstdlib>
    • -
  • <tr1/hashtable> no longer includes <memory> or <functional>
    • -
  • <tr1/memory> no longer includes <algorithm>
    • -
  • <tr1/random> no longer includes <algorithm> or <fstream>
    • -
- -

-Debug mode for <unordered_map> and <unordered_set>. -

- -

-Parallel mode first appears. -

- -

Variadic template implementations of items in <tuple> and - <functional>. -

- -

Default what implementations give more elaborate - exception strings for bad_cast, - bad_typeid, bad_exception, and - bad_alloc. -

- -

-PCH binary files no longer installed. Instead, the source files are installed. -

- -

-Namespace pb_ds moved to __gnu_pb_ds. -

- - - - diff --git a/libstdc++-v3/doc/html/17_intro/backwards_compatibility.html b/libstdc++-v3/doc/html/17_intro/backwards_compatibility.html deleted file mode 100644 index c9af980f0fc2..000000000000 --- a/libstdc++-v3/doc/html/17_intro/backwards_compatibility.html +++ /dev/null @@ -1,1073 +0,0 @@ - - - - - - - - - - Backwards Compatibility - - - - - - -

Backwards Compatibility

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/backwards_compatibility.html. -

- -

- To the libstdc++ homepage. -

- - -
-

- First. -

- -

The first generation GNU C++ library was called libg++. It was a -separate GNU project, although reliably paired with GCC. Rumors imply -that it had a working relationship with at least two kinds of -dinosaur. -

- -

Known Issues include many of the limitations of its immediate ancestor.

- -

Portability notes and known implementation limitations are as follows.

- -
No ios_base
- -

At least some older implementations don't have std::ios_base, so you should use std::ios::badbit, std::ios::failbit and std::ios::eofbit and std::ios::goodbit. -

- -
No cout in ostream.h, no cin in istream.h
- -

- In earlier versions of the standard, - <fstream.h>, - <ostream.h> - and <istream.h> - used to define - cout, cin and so on. ISO C++ specifies that one needs to include - <iostream> - explicitly to get the required definitions. -

-

Some include adjustment may be required.

- - -

This project is no longer maintained or supported, and the sources -archived. The code is considered replaced and rewritten. -

- -
-

- Second. -

-

The second generation GNU C++ library was called libstdc++, or -libstdc++-v2. It spans the time between libg++ and pre-ISO C++ -standardization and is usually associated with the following GCC -releases: egcs 1.x, gcc 2.95, and gcc 2.96. -

- -

The STL portions of this library are based on SGI/HP STL release 3.11. -

- -

Portability notes and known implementation limitations are as follows.

- -
Namespace std:: not supported
- -

- Some care is required to support C++ compiler and or library - implementation that do not have the standard library in - namespace std. -

-

- The following sections list some possible solutions to support compilers - that cannot ignore std::-qualified names. -

- -

First, see if the compiler has a flag for this. Namespace - back-portability-issues are generally not a problem for g++ - compilers that do not have libstdc++ in std::, as - the compilers use -fno-honor-std (ignore - std::, :: = std::) by default. That - is, the responsibility for enabling or disabling - std:: is on the user; the maintainer does not have - to care about it. This probably applies to some other compilers - as well. -

- -

Second, experiment with a variety of pre-processor tricks.

- -

By defining std as a macro, fully-qualified namespace calls become global. Volia.

- -
-#ifdef WICKEDLY_OLD_COMPILER
-# define std
-#endif
-
-(thanks to Juergen Heinzl who posted this solution on gnu.gcc.help) - -

Another pre-processor based approach is to define a -macro NAMESPACE_STD, which is defined to either -"" or "std" based on a compile-type test. On GNU -systems, this can be done with autotools by means of an autoconf test -(see below) for HAVE_NAMESPACE_STD, then using that to -set a value for the NAMESPACE_STD macro. At that point, -one is able to use NAMESPACE_STD::string, which will -evaluate to std::string or -::string (ie, in the global namespace on systems that do -not put string in std::).

- -
-dnl @synopsis AC_CXX_NAMESPACE_STD
-dnl
-dnl If the compiler supports namespace std, define
-dnl HAVE_NAMESPACE_STD.
-dnl
-dnl @category Cxx
-dnl @author Todd Veldhuizen
-dnl @author Luc Maisonobe <luc@spaceroots.org>
-dnl @version 2004-02-04
-dnl @license AllPermissive
-AC_DEFUN([AC_CXX_NAMESPACE_STD], [
-  AC_CACHE_CHECK(if g++ supports namespace std,
-  ac_cv_cxx_have_std_namespace,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([#include <iostream> 
-                  std::istream& is = std::cin;],,
-  ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_have_std_namespace" = yes; then
-    AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ])
-  fi
-])
-
- -
Illegal iterator usage
-

- The following illustrate implementation-allowed illegal iterator - use, and then correct use. -

- -

  • you cannot do - ostream::operator<<(iterator) to print the - address of the iterator => use operator<< - &*iterator instead -

    • -

  • you cannot clear an iterator's reference - (iterator = 0) => use - iterator = iterator_type(); -

    • -

  • -if (iterator) won't work any - more => use if (iterator != iterator_type()) -

    • -
- -
isspace from <cctype> is a macro -
- -

Glibc 2.0.x and 2.1.x define <ctype.h> -functionality as macros (isspace, isalpha etc.). -

- -

-This implementations of libstdc++, however, keep these functions as -macros, and so it is not back-portable to use fully qualified -names. For example: -

- -
 
-#include <cctype> 
-int main() { std::isspace('X'); } 
-
- -

Results in something like this: -

- -
 
-std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; 
-
- - -

A solution is to modify a header-file so that the compiler tells -<ctype.h> to define functions instead of macros: -

- -
-// This keeps isalnum, et al from being propagated as macros. 
-#if __linux__
-# define __NO_CTYPE 1
-#endif
-
- -

Then, include <ctype.h> -

- -

-Another problem arises if you put a using namespace std; -declaration at the top, and include <ctype.h>. This -will result in ambiguities between the definitions in the global -namespace (<ctype.h>) and the definitions in namespace -std:: (<cctype>). -

- -
No vector::at, deque::at, string::at
- -

- One solution is to add an autoconf-test for this: -

-
-AC_MSG_CHECKING(for container::at)
-AC_TRY_COMPILE(
-[
-#include <vector>
-#include <deque>
-#include <string>
-	
-using namespace std;
-],
-[
-deque<int> test_deque(3);
-test_deque.at(2);
-vector<int> test_vector(2);
-test_vector.at(1);
-string test_string("test_string");
-test_string.at(3);
-],
-[AC_MSG_RESULT(yes)
-AC_DEFINE(HAVE_CONTAINER_AT)],
-[AC_MSG_RESULT(no)])
-
- -

-If you are using other (non-GNU) compilers it might be a good idea -to check for string::at separately. -

- -
No std::char_traits<char>::eof
- -

-Use some kind of autoconf test, plus this: -

-
 
-#ifdef HAVE_CHAR_TRAITS
-#define CPP_EOF std::char_traits<char>::eof()
-#else
-#define CPP_EOF EOF
-#endif
-
- -
No string::clear
- -

- There are two functions for deleting the contents of a string: - clear and erase (the latter - returns the string). -

- -
-void 
-clear() { _M_mutate(0, this->size(), 0); }
-
-
-basic_string& 
-erase(size_type __pos = 0, size_type __n = npos)
-{ 
-  return this->replace(_M_check(__pos), _M_fold(__pos, __n),
-                          _M_data(), _M_data()); 
-}
-
- -

- Unfortunately, ut clear is not - implemented in this version, so you should use - erase (which is probably faster than - operator=(charT*)). -

- -
Removal of ostream::form and -istream::scan extensions
- -

These are no longer supported. Please use - - stringstreams instead. -

- -
No basic_stringbuf, basic_stringstream
- -

-Although the ISO standard -i/ostringstream-classes are provided, (<sstream>), for compatibility with older implementations the pre-ISO i/ostrstream (<strstream>) interface is also provided, with these caveats: -

- -
    -

  • strstream is considered to be - deprecated -

    • -

  • strstream is limited to - char -

    • -

  • with ostringstream you don't - have to take care of terminating the string or freeing its - memory -

    • -

  • istringstream can be re-filled - (clear(); str(input);) -

    • -
-

- You can then use output-stringstreams like this: -

- -
-#ifdef HAVE_SSTREAM
-# include <sstream>
-#else
-# include <strstream>
-#endif
-
-#ifdef HAVE_SSTREAM
-  std::ostringstream oss;
-#else
-  std::ostrstream oss;
-#endif
-
-oss << "Name=" << m_name << ", number=" << m_number << std::endl;
-...
-#ifndef HAVE_SSTREAM
-  oss << std::ends; // terminate the char*-string
-#endif
-
-// str() returns char* for ostrstream and a string for ostringstream
-// this also causes ostrstream to think that the buffer's memory
-// is yours
-m_label.set_text(oss.str());
-#ifndef HAVE_SSTREAM
-  // let the ostrstream take care of freeing the memory
-  oss.freeze(false);
-#endif
-
- -

- Input-stringstreams can be used similarly: -

- -
 
-std::string input;
-...
-#ifdef HAVE_SSTREAM
-std::istringstream iss(input);
-#else
-std::istrstream iss(input.c_str());
-#endif
-
-int i;
-iss >> i; 
-
- -

One (the only?) restriction is that an istrstream cannot be re-filled: -

- -
-std::istringstream iss(numerator);
-iss >> m_num;
-// this is not possible with istrstream
-iss.clear();
-iss.str(denominator);
-iss >> m_den;
-
- -

-If you don't care about speed, you can put these conversions in - a template-function: -

-
-template <class X>
-void fromString(const string& input, X& any)
-{
-#ifdef HAVE_SSTREAM
-std::istringstream iss(input);
-#else
-std::istrstream iss(input.c_str());
-#endif
-X temp;
-iss >> temp;
-if (iss.fail())
-throw runtime_error(..)
-any = temp;
-}
-
- -

Another example of using stringstreams is in this howto. -

- -

There is additional information in the libstdc++-v2 info files, in -particular "info iostream". -

- -
Little or no wide character support
- -
No templatized iostreams
- -
Thread safety issues
- -

This project is no longer maintained or supported, and the sources -archived. The code is considered replaced and rewritten. -

- - -
-

- Third. -

-

The third generation GNU C++ library is called libstdc++, or -libstdc++-v3. -

- -

The subset commonly known as the Standard Template Library - (chapters 23 through 25, mostly) is adapted from the final release - of the SGI STL (version 3.3), with extensive changes. -

- -

A more formal description of the V3 goals can be found in the - official design document. -

- -

Portability notes and known implementation limitations are as follows.

- -
Pre-ISO headers moved to backwards or removed
- -

The pre-ISO C++ headers - (iostream.h, defalloc.h etc.) are - available, unlike previous libstdc++ versions, but inclusion - generates a warning that you are using deprecated headers. -

- -

This compatibility layer is constructed by including the - standard C++ headers, and injecting any items in - std:: into the global namespace. -

-

For those of you new to ISO C++ (welcome, time travelers!), no, - that isn't a typo. Yes, the headers really have new names. - Marshall Cline's C++ FAQ Lite has a good explanation in item - [27.4]. -

- -

Some include adjustment may be required. What follows is an -autoconf test that defines PRE_STDCXX_HEADERS when they -exist.

- -
-# AC_HEADER_PRE_STDCXX
-AC_DEFUN([AC_HEADER_PRE_STDCXX], [
-  AC_CACHE_CHECK(for pre-ISO C++ include files,
-  ac_cv_cxx_pre_stdcxx,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -Wno-deprecated"	
-
-  # Omit defalloc.h, as compilation with newer compilers is problematic.
-  AC_TRY_COMPILE([
-  #include <new.h>
-  #include <iterator.h>
-  #include <alloc.h>
-  #include <set.h>
-  #include <hashtable.h>
-  #include <hash_set.h>
-  #include <fstream.h>
-  #include <tempbuf.h>
-  #include <istream.h>
-  #include <bvector.h>
-  #include <stack.h>
-  #include <rope.h>
-  #include <complex.h>
-  #include <ostream.h>
-  #include <heap.h>
-  #include <iostream.h>
-  #include <function.h>
-  #include <multimap.h>
-  #include <pair.h>
-  #include <stream.h>
-  #include <iomanip.h>
-  #include <slist.h>
-  #include <tree.h>
-  #include <vector.h>
-  #include <deque.h>
-  #include <multiset.h>
-  #include <list.h>
-  #include <map.h>
-  #include <algobase.h>
-  #include <hash_map.h>
-  #include <algo.h>
-  #include <queue.h>
-  #include <streambuf.h>
-  ],,
-  ac_cv_cxx_pre_stdcxx=yes, ac_cv_cxx_pre_stdcxx=no)
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_pre_stdcxx" = yes; then
-    AC_DEFINE(PRE_STDCXX_HEADERS,,[Define if pre-ISO C++ header files are present. ])
-  fi
-])
-
- -

Porting between pre-ISO headers and ISO headers is simple: headers -like <vector.h> can be replaced with <vector> and a using -directive using namespace std; can be put at the global -scope. This should be enough to get this code compiling, assuming the -other usage is correct. -

- -
Extension headers hash_map, hash_set moved to ext or backwards
- -

Header files hash_map and hash_set moved -to ext/hash_map and ext/hash_set, -respectively. At the same time, all types in these files are enclosed -in namespace __gnu_cxx. Later versions move deprecate -these files, and suggest using TR1's unordered_map -and unordered_set instead. -

- -

The following autoconf tests check for working HP/SGI hash containers. -

- -
-# AC_HEADER_EXT_HASH_MAP
-AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [
-  AC_CACHE_CHECK(for ext/hash_map,
-  ac_cv_cxx_ext_hash_map,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -Werror"	
-  AC_TRY_COMPILE([#include <ext/hash_map>], [using __gnu_cxx::hash_map;],
-  ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no)
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_ext_hash_map" = yes; then
-    AC_DEFINE(HAVE_EXT_HASH_MAP,,[Define if ext/hash_map is present. ])
-  fi
-])
-
- -
-# AC_HEADER_EXT_HASH_SET
-AC_DEFUN([AC_HEADER_EXT_HASH_SET], [
-  AC_CACHE_CHECK(for ext/hash_set,
-  ac_cv_cxx_ext_hash_set,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -Werror"	
-  AC_TRY_COMPILE([#include <ext/hash_set>], [using __gnu_cxx::hash_set;],
-  ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no)
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_ext_hash_set" = yes; then
-    AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ])
-  fi
-])
-
- - -
-No ios::nocreate/ios::noreplace. -
- -

The existence of ios::nocreate being used for -input-streams has been confirmed, most probably because the author -thought it would be more correct to specify nocreate explicitly. So -it can be left out for input-streams. -

- -

For output streams, "nocreate" is probably the default, -unless you specify std::ios::trunc ? To be safe, you can -open the file for reading, check if it has been opened, and then -decide whether you want to create/replace or not. To my knowledge, -even older implementations support app, ate -and trunc (except for app ?). -

- - -
-No stream::attach(int fd) -
- -

- Phil Edwards writes: It was considered and rejected for the ISO - standard. Not all environments use file descriptors. Of those - that do, not all of them use integers to represent them. -

- -

- For a portable solution (among systems which use - filedescriptors), you need to implement a subclass of - std::streambuf (or - std::basic_streambuf<..>) which opens a file - given a descriptor, and then pass an instance of this to the - stream-constructor. -

- -

- An extension is available that implements this. - <ext/stdio_filebuf.h> contains a derived class called - __gnu_cxx::stdio_filebuf. - This class can be constructed from a C FILE* or a file - descriptor, and provides the fd() function. -

- -

- For another example of this, refer to - fdstream example - by Nicolai Josuttis. -

- -
-Support for C++98 dialect. -
- -

Check for complete library coverage of the C++1998/2003 standard. -

- -
-
-# AC_HEADER_STDCXX_98
-AC_DEFUN([AC_HEADER_STDCXX_98], [
-  AC_CACHE_CHECK(for ISO C++ 98 include files,
-  ac_cv_cxx_stdcxx_98,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([
-    #include <cassert>
-    #include <cctype>
-    #include <cerrno>
-    #include <cfloat>
-    #include <ciso646>
-    #include <climits>
-    #include <clocale>
-    #include <cmath>
-    #include <csetjmp>
-    #include <csignal>
-    #include <cstdarg>
-    #include <cstddef>
-    #include <cstdio>
-    #include <cstdlib>
-    #include <cstring>
-    #include <ctime>
-
-    #include <algorithm>
-    #include <bitset>
-    #include <complex>
-    #include <deque>
-    #include <exception>
-    #include <fstream>
-    #include <functional>
-    #include <iomanip>
-    #include <ios>
-    #include <iosfwd>
-    #include <iostream>
-    #include <istream>
-    #include <iterator>
-    #include <limits>
-    #include <list>
-    #include <locale>
-    #include <map>
-    #include <memory>
-    #include <new>
-    #include <numeric>
-    #include <ostream>
-    #include <queue>
-    #include <set>
-    #include <sstream>
-    #include <stack>
-    #include <stdexcept>
-    #include <streambuf>
-    #include <string>
-    #include <typeinfo>
-    #include <utility>
-    #include <valarray>
-    #include <vector>
-  ],,
-  ac_cv_cxx_stdcxx_98=yes, ac_cv_cxx_stdcxx_98=no)
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_stdcxx_98" = yes; then
-    AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ])
-  fi
-])
-
- - -
-Support for C++TR1 dialect. -
- -

Check for library coverage of the TR1 standard. -

- -
-
-# AC_HEADER_STDCXX_TR1
-AC_DEFUN([AC_HEADER_STDCXX_TR1], [
-  AC_CACHE_CHECK(for ISO C++ TR1 include files,
-  ac_cv_cxx_stdcxx_tr1,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([
-  #include <tr1/array>
-  #include <tr1/ccomplex>
-  #include <tr1/cctype>
-  #include <tr1/cfenv>
-  #include <tr1/cfloat>
-  #include <tr1/cinttypes>
-  #include <tr1/climits>
-  #include <tr1/cmath>
-  #include <tr1/complex>
-  #include <tr1/cstdarg>
-  #include <tr1/cstdbool>
-  #include <tr1/cstdint>
-  #include <tr1/cstdio>
-  #include <tr1/cstdlib>
-  #include <tr1/ctgmath>
-  #include <tr1/ctime>
-  #include <tr1/cwchar>
-  #include <tr1/cwctype>
-  #include <tr1/functional>
-  #include <tr1/memory>
-  #include <tr1/random>
-  #include <tr1/regex>
-  #include <tr1/tuple>
-  #include <tr1/type_traits>
-  #include <tr1/unordered_set>
-  #include <tr1/unordered_map>
-  #include <tr1/utility>
-  ],,
-  ac_cv_cxx_stdcxx_tr1=yes, ac_cv_cxx_stdcxx_tr1=no)
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_stdcxx_tr1" = yes; then
-    AC_DEFINE(STDCXX_TR1_HEADERS,,[Define if ISO C++ TR1 header files are present. ])
-  fi
-])
-
- -

An alternative is to check just for specific TR1 includes, such as <unordered_map> and <unordered_set>. -

- -
-# AC_HEADER_TR1_UNORDERED_MAP
-AC_DEFUN([AC_HEADER_TR1_UNORDERED_MAP], [
-  AC_CACHE_CHECK(for tr1/unordered_map,
-  ac_cv_cxx_tr1_unordered_map,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([#include <tr1/unordered_map>], [using std::tr1::unordered_map;],
-  ac_cv_cxx_tr1_unordered_map=yes, ac_cv_cxx_tr1_unordered_map=no)
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_tr1_unordered_map" = yes; then
-    AC_DEFINE(HAVE_TR1_UNORDERED_MAP,,[Define if tr1/unordered_map is present. ])
-  fi
-])
-
- -
-# AC_HEADER_TR1_UNORDERED_SET
-AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [
-  AC_CACHE_CHECK(for tr1/unordered_set,
-  ac_cv_cxx_tr1_unordered_set,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([#include <tr1/unordered_set>], [using std::tr1::unordered_set;],
-  ac_cv_cxx_tr1_unordered_set=yes, ac_cv_cxx_tr1_unordered_set=no)
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_tr1_unordered_set" = yes; then
-    AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ])
-  fi
-])
-
- - - -
-Support for C++0x dialect. -
- -

Check for baseline language coverage in the compiler for the C++0xstandard. -

- -
-# AC_COMPILE_STDCXX_OX
-AC_DEFUN([AC_COMPILE_STDCXX_0X], [
-  AC_CACHE_CHECK(if g++ supports C++0x features without additional flags,
-  ac_cv_cxx_compile_cxx0x_native,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([
-  template <typename T>
-    struct check 
-    {
-      static_assert(sizeof(int) <= sizeof(T), "not big enough");
-    };
-
-    typedef check<check<bool>> right_angle_brackets;
-
-    int a;
-    decltype(a) b;
-
-    typedef check<int> check_type;
-    check_type c;
-    check_type&& cr = c;],,
-  ac_cv_cxx_compile_cxx0x_native=yes, ac_cv_cxx_compile_cxx0x_native=no)
-  AC_LANG_RESTORE
-  ])
-
-  AC_CACHE_CHECK(if g++ supports C++0x features with -std=c++0x,
-  ac_cv_cxx_compile_cxx0x_cxx,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=c++0x"	
-  AC_TRY_COMPILE([
-  template <typename T>
-    struct check 
-    {
-      static_assert(sizeof(int) <= sizeof(T), "not big enough");
-    };
-
-    typedef check<check<bool>> right_angle_brackets;
-
-    int a;
-    decltype(a) b;
-
-    typedef check<int> check_type;
-    check_type c;
-    check_type&& cr = c;],,
-  ac_cv_cxx_compile_cxx0x_cxx=yes, ac_cv_cxx_compile_cxx0x_cxx=no)
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  AC_LANG_RESTORE
-  ])
-
-  AC_CACHE_CHECK(if g++ supports C++0x features with -std=gnu++0x,
-  ac_cv_cxx_compile_cxx0x_gxx,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
-  AC_TRY_COMPILE([
-  template <typename T>
-    struct check 
-    {
-      static_assert(sizeof(int) <= sizeof(T), "not big enough");
-    };
-
-    typedef check<check<bool>> right_angle_brackets;
-
-    int a;
-    decltype(a) b;
-
-    typedef check<int> check_type;
-    check_type c;
-    check_type&& cr = c;],,
-  ac_cv_cxx_compile_cxx0x_gxx=yes, ac_cv_cxx_compile_cxx0x_gxx=no)
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  AC_LANG_RESTORE
-  ])
-
-  if test "$ac_cv_cxx_compile_cxx0x_native" = yes || 
-     test "$ac_cv_cxx_compile_cxx0x_cxx" = yes || 
-     test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then
-    AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ])
-  fi
-])
-
- - -

Check for library coverage of the C++0xstandard. -

- -
-
-# AC_HEADER_STDCXX_0X
-AC_DEFUN([AC_HEADER_STDCXX_0X], [
-  AC_CACHE_CHECK(for ISO C++ 0x include files,
-  ac_cv_cxx_stdcxx_0x,
-  [AC_REQUIRE([AC_COMPILE_STDCXX_0X])
-  AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
-
-  AC_TRY_COMPILE([
-    #include <cassert>
-    #include <ccomplex>
-    #include <cctype>
-    #include <cerrno>
-    #include <cfenv>
-    #include <cfloat>
-    #include <cinttypes>
-    #include <ciso646>
-    #include <climits>
-    #include <clocale>
-    #include <cmath>
-    #include <csetjmp>
-    #include <csignal>
-    #include <cstdarg>
-    #include <cstdbool>
-    #include <cstddef>
-    #include <cstdint>
-    #include <cstdio>
-    #include <cstdlib>
-    #include <cstring>
-    #include <ctgmath>
-    #include <ctime>
-    #include <cwchar>
-    #include <cwctype>
-
-    #include <algorithm>
-    #include <array>
-    #include <bitset>
-    #include <complex>
-    #include <deque>
-    #include <exception>
-    #include <fstream>
-    #include <functional>
-    #include <iomanip>
-    #include <ios>
-    #include <iosfwd>
-    #include <iostream>
-    #include <istream>
-    #include <iterator>
-    #include <limits>
-    #include <list>
-    #include <locale>
-    #include <map>
-    #include <memory>
-    #include <new>
-    #include <numeric>
-    #include <ostream>
-    #include <queue>
-    #include <random>
-    #include <regex>
-    #include <set>
-    #include <sstream>
-    #include <stack>
-    #include <stdexcept>
-    #include <streambuf>
-    #include <string>
-    #include <tuple>
-    #include <typeinfo>
-    #include <type_traits>
-    #include <unordered_map>
-    #include <unordered_set>
-    #include <utility>
-    #include <valarray>
-    #include <vector>
-  ],,
-  ac_cv_cxx_stdcxx_0x=yes, ac_cv_cxx_stdcxx_0x=no)
-  AC_LANG_RESTORE
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  ])
-  if test "$ac_cv_cxx_stdcxx_0x" = yes; then
-    AC_DEFINE(STDCXX_0X_HEADERS,,[Define if ISO C++ 0x header files are present. ])
-  fi
-])
-
- -

As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For <unordered_map> -

- -
-
-# AC_HEADER_UNORDERED_MAP
-AC_DEFUN([AC_HEADER_UNORDERED_MAP], [
-  AC_CACHE_CHECK(for unordered_map,
-  ac_cv_cxx_unordered_map,
-  [AC_REQUIRE([AC_COMPILE_STDCXX_0X])
-  AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
-  AC_TRY_COMPILE([#include <unordered_map>], [using std::unordered_map;],
-  ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no)
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_unordered_map" = yes; then
-    AC_DEFINE(HAVE_UNORDERED_MAP,,[Define if unordered_map is present. ])
-  fi
-])
-
- -
-# AC_HEADER_UNORDERED_SET
-AC_DEFUN([AC_HEADER_UNORDERED_SET], [
-  AC_CACHE_CHECK(for unordered_set,
-  ac_cv_cxx_unordered_set,
-  [AC_REQUIRE([AC_COMPILE_STDCXX_0X])
-  AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
-  AC_TRY_COMPILE([#include <unordered_set>], [using std::unordered_set;],
-  ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no)
-  CXXFLAGS="$ac_save_CXXFLAGS"
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_unordered_set" = yes; then
-    AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ])
-  fi
-])
-
- - -
-Container iterator_type is not necessarily container value_type* -
- - -
-

- Fourth, and future -

- -
-

- Links -

- -

-Migrating to gcc-4.1, by Dan Kegel. -

- -

-Building the whole Debian archive with GCC 4.1: a summary, by Martin Michlmayr -

- -

-Migration guide for GCC-3.2 -

- - - - diff --git a/libstdc++-v3/doc/html/17_intro/c++0x_status.html b/libstdc++-v3/doc/html/17_intro/c++0x_status.html deleted file mode 100644 index cfc28ed44a5d..000000000000 --- a/libstdc++-v3/doc/html/17_intro/c++0x_status.html +++ /dev/null @@ -1,2290 +0,0 @@ - - - - - - - - - - - - Status of C++0x features in GCC - - GNU Project - Free Software Foundation (FSF) - - - - - - -

- Status of C++0x features in GCC -

- -

-This table is based on the table of contents of ISO/IEC -Doc No: N2461=07-0331 Date: 2007-10-22 -Working Draft, Standard for Programming Language C++ -

- -

-In this implementation -std=gnu++0x or --std=c++0x flags must be used to enable language and -library features. The pre-defined symbol -__GXX_EXPERIMENTAL_CXX0X__ is used to check for the -presence of the required flag. -

- -

-This page describes the C++0x support in mainline GCC SVN, not in any -particular release. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SectionDescriptionDoneBrokenMissingComments
20General Utilities
20.2Utility Componentsincomplete
20.2.1Operatorspartial
20.2.2forward/move helperspartial
20.2.3Pairsdone
20.3Header <tuple> synopsisdone
20.3.1Class template tupledone
20.3.1.1Constructiondone
20.3.1.2Tuple creation functionsdone
20.3.1.3Tuple helper classesdone
20.3.1.4Element accessdone
20.3.1.5Relational operatorsdone
20.4Metaprogramming and type traits
20.4.1Requirementsdone
20.4.2Header <type_traits> synopsisdone
20.4.3Helper classesdone
20.4.4General Requirementsdone
20.4.5Unary Type Traitsdone
20.4.5.1Primary Type Categoriesdone
20.4.5.2Composite type traitsdone
20.4.5.3Type propertiesdone
20.4.6Relationships between typesdone
20.4.7Transformations between typesdone
20.4.7.1Const-volatile modificationsdone
20.4.7.2Reference modificationsdone
20.4.7.3Array modificationsdone
20.4.7.4Pointer modificationsdone
20.4.8Other transformationsdone
20.4.9Implementation requirementsdone
20.5 Function Objectsdone
20.5Additions to header <functional> synopsisdone
20.5.1Definitionsdone
20.5.2Requirementsdone
20.5.3Basedone
20.5.4Function return typesdone
20.5.5Class template reference_wrapperdone
20.5.5.1reference_wrapper construct/copy/destroydone
20.5.5.2reference_wrapper assignmentdone
20.5.5.3reference_wrapper accessdone
20.5.5.4reference_wrapper invocationdone
20.5.5.5reference_wrapper helper functionsdone
20.5.14Function template mem_fndone
20.5.11Template function binddone
20.5.11.1Function object bindersdone
20.5.11.1.1Class template is_bind_expressiondone
20.5.11.1.2Class template is_placeholderdone
20.5.11.1.3Function template binddone
20.5.11.1.4Placeholdersdone
20.5.15Polymorphic function wrappersdone
20.5.15.1Class bad_function_calldone
20.5.15.1.1bad_function_call constructordone
20.5.15.2Class template functiondone
20.5.15.2.1function construct/copy/destroydone
20.5.15.2.2function modifiersdone
20.5.15.2.3function capacitydone
20.5.15.2.4function invocationdone
20.5.15.2.5function target accessdone
20.5.15.2.7null pointer comparison operatorsdone
20.5.15.2.8specialized algorithmsdone
20.5.16Class template hashdone
20.6Additions to header <memory> synopsispartialmissing unique_ptr
20.6.5Class template unique_ptrmissing
20.6.6Smart pointersdone
20.6.6.1Class bad_weak_ptrdone
20.6.6.2Class template shared_ptrdone1
20.6.6.2.1shared_ptr constructorsdone
20.6.6.2.2shared_ptr destructordone
20.6.6.2.3shared_ptr assignmentdone
20.6.6.2.4shared_ptr modifiersdone
20.6.6.2.5shared_ptr observersdone
20.6.6.2.6shared_ptr creationdone - N2351 -
20.6.6.2.7shared_ptr comparisondone
20.6.6.2.8shared_ptr I/Odone
20.6.6.2.9shared_ptr specialized algorithmsdone
20.6.6.2.10shared_ptr castsdone
20.6.6.2.11get_deleterdone
20.6.6.3Class template weak_ptrdone
20.6.6.3.1weak_ptr constructorsdone
20.6.6.3.2weak_ptr destructordone
20.6.6.3.3weak_ptr assignmentdone
20.6.6.3.4weak_ptr modifiersdone
20.6.6.3.5weak_ptr observersdone
20.6.6.3.6weak_ptr comparisondone
20.6.6.3.7weak_ptr specialized algorithmsdone
20.6.6.4Class template enable_shared_from_thisdone
23Containers
23.2.1Header <array> synopsisdone
23.2.1Class template arraydone
23.2.1.1array constructors, copy, and assignmentdone
23.2.1.2array specialized algorithmsdone
23.2.1.3array sizedone
23.2.1.4array datadone
23.2.1.5Zero sized arraysdone
23.2.1.6Tuple interface to class template arraydone
23.4Unordered associative containersdone
23.4.1Class template unordered_mapdone
23.4.1.1unordered_map constructorsdone
23.4.1.2unordered_map element accessdone
23.4.1.3unordered_map swapdone
23.4.2Class template unordered_multimapdone
23.4.2.1unordered_multimap constructorsdone
23.4.2.2unordered_multimap swapdone
23.4.3Class template unordered_setdone
23.4.3.1unordered_set constructorsdone
23.4.3.2unordered_set swapdone
23.4.4Class template unordered_multisetdone
23.4.4.1unordered_multiset constructorsdone
23.4.4.2unordered_multiset swapdone
26Numerics
26.4Random number generationdone
26.4.1Requirementsdone
26.4.2Header <random> synopsispartial
26.4.3Random number engine class templatesdone
26.4.3.1Class template linear_congruential_enginedone
26.4.3.2Class template mersenne_twister_enginedone
26.4.3.3Class template subtract_with_carry_enginedone
26.4.4Random number engine adaptor class templatesdone
26.4.4.1Class template discard_block_enginedone
26.4.4.2Class template independent_bits_enginedone
26.4.4.3Class template shuffle_order_enginedone
26.4.4.4Class template xor_combine_enginedoneoperator()() per N2079
26.4.5Engines and engine adaptors with predefined parametersdone
26.4.6Class random_devicedone
26.4.7Utilitiesdone
26.4.7.1Class seed_seqmissing
26.4.7.2Function template generate_cannonicalmissing
26.4.8Random number generation class templatesdone
26.4.8.1Uniform distributionspartial
26.4.8.1Class template uniform_int_distributionmissing
26.4.8.1Class template uniform_real_distributionmissing
26.4.8.2Bernoulli distributionspartial
26.4.8.2.1Class bernoulli_distributiondone
26.4.8.2.2Class template binomial_distributiondone
26.4.8.2.3Class template geometric_distributiondone
26.4.8.2.4Class template negative_binomial_distributionmissing
26.4.8.3Poisson distributionspartial
26.4.8.3.1Class template poisson_distributiondone
26.4.8.3.2Class template exponential_distributiondone
26.4.8.3.3Class template gamma_distributiondone
26.4.8.3.4Class template weibull_distributionmissing
26.4.8.3.5Class template extreme_value_distributionmissing
26.4.8.4Normal distributionspartial
26.4.8.4.1Class template normal_distributiondone
26.4.8.4.2Class template lognormal_distributionmissing
26.4.8.4.3Class template chi_squared_distributionmissing
26.4.8.4.4Class template cauchy_distributionmissing
26.4.8.4.5Class template fisher_f_distributionmissing
26.4.8.4.6Class template student_t_distributionmissing
26.4.8.5Sampling distributionsmissing
26.4.8.5.1Class template discrete_distributionmissing
26.4.8.5.1Class template piecewise_constant_distributionmissing
26.4.8.5.1Class template general_pdf_distributionmissing
28Regular expressions
28.1Definitionsmissing
28.2Requirementsmissing
28.3Regular expressions summarymissing
28.4Header <regex> synopsismissing
28.5Namespace tr1::regex_constantsmissing
28.5.1Bitmask Type syntax_option_typemissing
28.5.2Bitmask Type regex_constants::match_flag_typemissing
28.5.3Implementation defined error_typemissing
28.6Class regex_errormissing
28.7Class template regex_traitsmissing
28.8Class template basic_regexmissing
28.8.1basic_regex constantsmissing
28.8.2basic_regex constructorsmissing
28.8.3basic_regex assignmissing
28.8.4basic_regex constant operationsmissing
28.8.5basic_regex localemissing
28.8.6basic_regex swapmissing
28.8.7basic_regex non-member functionsmissing
28.8.7.1basic_regex non-member swapmissing
28.9Class template sub_matchmissing
28.9.1sub_match membersmissing
28.9.2sub_match non-member operatorsmissing
28.10Class template match_resultsmissing
28.10.1match_results constructorsmissing
28.10.2match_results sizemissing
28.10.3match_results element accessmissing
28.10.4match_results formattingmissing
28.10.5match_results allocatormissing
28.10.6match_results swapmissing
28.11Regular expression algorithmsmissing
28.11.1exceptionsmissing
28.11.2regex_matchmissing
28.11.3regex_searchmissing
28.11.4regex_replacemissing
28.12Regular expression Iteratorsmissing
28.12.1Class template regex_iteratormissing
28.12.1.1regex_iterator constructorsmissing
28.12.1.2regex_iterator comparisonsmissing
28.12.1.3regex_iterator dereferencemissing
28.12.1.4regex_iterator incrementmissing
28.12.2Class template regex_token_iteratormissing
28.12.2.1regex_token_iterator constructorsmissing
28.12.2.2regex_token_iterator comparisonsmissing
28.12.2.3regex_token_iterator dereferencemissing
28.12.2.4regex_token_iterator incrementmissing
28.13Modified ECMAScript regular expression grammarmissing
CC compatibility
C2.1Additions to header <complex>done
C2.1.1Synopsisdone
C2.1.2Function acosdone
C2.1.3Function asindone
C2.1.4Function atandone
C2.1.5Function acoshdone
C2.1.6Function asinhdone
C2.1.7Function atanhdone
C2.1.8Function fabsdone
C2.1.9Additional Overloadsdone
C2.2Header <ccomplex>missingDR 551
C2.3Header <complex.h>missingDR 551
C2.4Additions to header <cctype>done
C2.4.1Synopsisdone
C2.4.2Function isblankdone
C2.5Additions to header <ctype.h>done
C2.6Header <cfenv>done
C2.6.1Synopsisdone
C2.6.2Definitionsdone
C2.7Header <fenv.h>done
C2.8Additions to header <cfloat>done
C2.9Additions to header <float.h>done
C2.10Additions to header <ios>missing
C2.10.1Synopsismissing
C2.10.2Function hexfloatmissing
C2.11Header <cinttypes>done
C2.11.1SynopsisdoneDR 557
C2.11.2Definitionsdone
C2.12Header <inttypes.h>done
C2.13Additions to header <climits>done
C2.14Additions to header <limits.h>done
C2.15Additions to header <locale>missing
C2.16Additions to header <cmath>done
C2.16.1Synopsisdone
C2.16.2Definitionsdone
C2.16.3Function template definitionsdone
C2.16.4Additional overloadsdoneDR 568; DR 550
C2.17Additions to header <math.h>done
C2.18Additions to header <cstdarg>done
C2.19Additions to header <stdarg.h>done
C2.20The header <cstdbool>done
C2.21The header <stdbool.h>done
C2.22The header <cstdint>done
C2.22.1Synopsisdone
C2.22.2Definitionsdone
C2.23The header <stdint.h>done
C2.24Additions to header <cstdio>done
C2.24.1Synopsisdone
C2.24.2Definitionsdone
C2.24.3Additional format specifiersdoneC library responsibility
C2.24.4Additions to header <stdio.h>done
C2.25Additions to header <cstdlib>done
C2.25.1Synopsisdone
C2.25.2Definitionsdone
C2.25.3Function absdone
C2.25.4Function divdone
C2.26Additions to header <stdlib.h>done
C2.27Header <ctgmath>doneDR 551
C2.28Header <tgmath.h>doneDR 551
C2.29Additions to header <ctime>doneC library responsibility
C2.30Additions to header <cwchar>done
C2.30.1Synopsisdone
C2.30.2Definitionsdone
C2.30.3Additional wide format specifiersdoneC library responsibility
C2.31Additions to header <wchar.h>done
C2.32Additions to header <cwctype>done
C2.32.1Synopsisdone
C2.32.2Function iswblankdone
C2.33Additions to header <wctype.h>done
DCompatibility Features
D.6Old iostream membersdone
D.8Bindersdone33911
D.9Class template auto_ptrdone33911
- -

Footnotes

- -
    - -
  1. - - The shared_ptr implementation uses some code from the - Boost - shared_ptr library. -
    2. - -
- -

-Please send FSF & GNU inquiries & questions to -gnu@gnu.org. -There are also other ways -to contact the FSF. -

- -

-These pages are maintained by -the GCC team. -

- -
-For questions related to the use of GCC, please consult these web -pages and the GCC manuals. If -that fails, the gcc-help@gcc.gnu.org -mailing list might help.
-Please send comments on these web pages and the development of GCC to our -developer mailing list at gcc@gnu.org -or gcc@gcc.gnu.org. All of our lists -have public archives. -
- -

-Copyright (C) Free Software Foundation, Inc., -51 Franklin St, Fifth Floor, Boston, MA 02110, USA. -

-

-Verbatim copying and distribution of this entire article is -permitted in any medium, provided this notice is preserved. -

- - - - - - -
- Last modified 2007-10-30 - - - Valid XHTML 1.0 - -
- - - diff --git a/libstdc++-v3/doc/html/17_intro/c++1998_status.html b/libstdc++-v3/doc/html/17_intro/c++1998_status.html deleted file mode 100644 index 7865e6499822..000000000000 --- a/libstdc++-v3/doc/html/17_intro/c++1998_status.html +++ /dev/null @@ -1,6004 +0,0 @@ -
-
-   Completion Checklist for the Standard C++ Library
-   Updated: 2003-04-25
-
-   Status Code Legend:
-    M - Missing
-    S - Present as stub.
-    X - Partially implemented, or buggy.
-    T - Implemented, pending test/inspection.
-    V - Verified to pass all available test suites.
-    Q - Qualified by inspection for non-testable correctness.
-    P - Portability verified.
-    C - Certified.
-
-   Lexical notes:
-   Only status codes appear in column 0.  Notes relating to conformance
-   issues appear [in brackets].
-
-   Note that this checklist does not (yet) include all emendations
-   recommended by the ISO Library Working Group:
-   http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-toc.html
-
-   Detailed explanation of status codes:
-
-    M - Missing:  The name is not visible to programs that include
-        the specified header, either at compile or link stage.
-
-    S - Present as stub:  A program can use the name, but no implementation
-        is provided.  Programs that use the name link correctly, but
-        cannot usefully be run.
-
-    X - Partially implemented, or buggy:  Some implementation has been
-        provided, but it is known or believed not to conform fully.
-        It may have an incorrect base class, wrong namespace, wrong
-        storage class, or simply not fully implement requirements.
-        However, it may be sufficiently usable to help test other
-        components.
-
-    T - Implemented, pending test/inspection:  Implementation believed
-        to be complete, and informal testing suggests it is ready for
-        formal verification.
-
-    V - Verified, passes all test suites:  Verified to satisfy all
-        generically testable conformance requirements.
-
-    Q - Qualified by inspection for non-testable correctness:
-        Inspected, "implementation-defined" documentation accepted,
-        local usability criteria satisfied, formally inspected for
-        other untestable conformance.  (Untestable requirements
-        include exception-safety, thread-safety, worst-case
-        complexity, memory cleanliness, usefulness.)
-
-    P - Portability verified:  Qualified on all primary target platforms.
-
-    C - Certified:  Formally certified to have passed all tests,
-        inspections, qualifications; approved under "signing authority"
-        to be used to satisfy contractual guarantees.
-
-   ----------------------------------------------------------------------
-                          
-                                 
-                                  
-X                          
-                             
-                      
-          
-
-   [C header names must be in std:: to qualify.  Related to shadow/ dir.]
-                
-                
-X               
-                
-
-    Macro:
-X   errno,  declared  or  defined in .
-
-    Macro fn:
-X   setjmp(jmp_buf), declared or defined in 
-X   va_end(va_list), declared or defined in 
-
-    Types:
-X   clock_t, div_t, FILE, fpos_t, lconv, ldiv_t, mbstate_t,
-X   ptrdiff_t, sig_atomic_t, size_t,  time_t,  tm,  va_list,
-X   wctrans_t, wctype_t, and wint_t.
-
-   1 Which  of  the functions in the C++ Standard Library are not reentrant
-    subroutines is implementation-defined.
-
-   18.1  Types                                        [lib.support.types]
-X      
-X      NULL
-X      offsetof
-X      ptrdiff_t
-X      size_t
-
-   18.2  Implementation properties                   [lib.support.limits]
-
-    , , and 
-
-   18.2.1  Numeric limits                                    [lib.limits]
-
-X   template class numeric_limits;
-
-T   enum float_round_style;
-T   enum float_denorm_style;
-
-T   template<> class numeric_limits;
-
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-T   template<> class numeric_limits;
-
-X   template<> class numeric_limits;
-X   template<> class numeric_limits;
-X   template<> class numeric_limits;
-
-   18.2.1.1  Template class numeric_limits           [lib.numeric.limits]
-T   template class numeric_limits {
-    public:
-T     static const bool is_specialized = false;
-T     static T min() throw();
-T     static T max() throw();
-T     static const int  digits = 0;
-T     static const int  digits10 = 0;
-T     static const bool is_signed = false;
-T     static const bool is_integer = false;
-T     static const bool is_exact = false;
-T     static const int  radix = 0;
-T     static T epsilon() throw();
-T     static T round_error() throw();
-
-T     static const int  min_exponent = 0;
-T     static const int  min_exponent10 = 0;
-T     static const int  max_exponent = 0;
-T     static const int  max_exponent10 = 0;
-
-T     static const bool has_infinity = false;
-T     static const bool has_quiet_NaN = false;
-T     static const bool has_signaling_NaN = false;
-T     static const float_denorm_style has_denorm = denorm_absent;
-T     static const bool has_denorm_loss = false;
-T     static T infinity() throw();
-T     static T quiet_NaN() throw();
-T     static T signaling_NaN() throw();
-T     static T denorm_min() throw();
-
-T     static const bool is_iec559 = false;
-T     static const bool is_bounded = false;
-T     static const bool is_modulo = false;
-
-T     static const bool traps = false;
-T     static const bool tinyness_before = false;
-T     static const float_round_style round_style = round_toward_zero;
-    };
-
-   18.2.1.3  Type float_round_style                     [lib.round.style]
-
-T   enum float_round_style {
-T     round_indeterminate       = -1,
-T     round_toward_zero         =  0,
-T     round_to_nearest          =  1,
-T     round_toward_infinity     =  2,
-T     round_toward_neg_infinity =  3
-    };
-
-   18.2.1.4  Type float_denorm_style                   [lib.denorm.style]
-
-T   enum float_denorm_style {
-T     denorm_indeterminate = -1;
-T     denorm_absent = 0;
-T     denorm present = 1;
-    };
-
-   18.2.1.5  numeric_limits specializations         [lib.numeric.special]
-   
-   [Note: see Note at 18.2.1.  ]
-
-   18.2.2  C Library                                       [lib.c.limits]
-
-   1 Header  (Table 3):
-      CHAR_BIT   INT_MAX    LONG_MIN     SCHAR_MIN   UCHAR_MAX   USHRT_MAX
-X     CHAR_MAX   INT_MIN    MB_LEN_MAX   SHRT_MAX    UINT_MAX
-      CHAR_MIN   LONG_MAX   SCHAR_MAX    SHRT_MIN    ULONG_MAX
-
-   3 Header  (Table 4):
-
-    DBL_DIG          DBL_MIN_EXP      FLT_MIN_10_EXP   LDBL_MAX_10_EXP
-    DBL_EPSILON      FLT_DIG          FLT_MIN_EXP      LDBL_MAX_EXP
-    DBL_MANT_DIG     FLT_EPSILON      FLT_RADIX        LDBL_MIN
-X   DBL_MAX          FLT_MANT_DIG     FLT_ROUNDS       LDBL_MIN_10_EXP
-    DBL_MAX_10_EXP   FLT_MAX          LDBL_DIG         LDBL_MIN_EXP
-    DBL_MAX_EXP      FLT_MAX_10_EXP   LDBL_EPSILON
-    DBL_MIN          FLT_MAX_EXP      LDBL_MANT_DIG
-    DBL_MIN_10_EXP   FLT_MIN          LDBL_MAX
-
-
-        1 Header  (partial), Table 5:
-X             EXIT_FAILURE     EXIT_SUCCESS
-              abort   atexit   exit
-
-S    abort(void)
-S    extern "C" int atexit(void (*f)(void))
-S    extern "C++" int atexit(void (*f)(void))
-S    exit(int status)
-
-   18.4  Dynamic memory management                  [lib.support.dynamic]
-
-   Header  synopsis
-
-T    class bad_alloc;
-T    struct nothrow_t {};
-T    extern const nothrow_t nothrow;
-T    typedef void (*new_handler)();
-T    new_handler set_new_handler(new_handler new_p) throw();
-
-T    void* operator new(std::size_t size) throw(std::bad_alloc);
-T    void* operator new(std::size_t size, const std::nothrow_t&) throw();
-T    void  operator delete(void* ptr) throw();
-T    void  operator delete(void* ptr, const std::nothrow_t&) throw();
-T    void* operator new[](std::size_t size) throw(std::bad_alloc);
-T    void* operator new[](std::size_t size, const std::nothrow_t&) throw();
-T    void  operator delete[](void* ptr) throw();
-T    void  operator delete[](void* ptr, const std::nothrow_t&) throw();
-T    void* operator new  (std::size_t size, void* ptr) throw();
-T    void* operator new[](std::size_t size, void* ptr) throw();
-T    void  operator delete  (void* ptr, void*) throw();
-T    void  operator delete[](void* ptr, void*) throw();
-
-   18.4.2.1  Class bad_alloc                              [lib.bad.alloc]
-
-T   class bad_alloc : public exception {
-    public:
-T     bad_alloc() throw();
-T     bad_alloc(const bad_alloc&) throw();
-T     bad_alloc& operator=(const bad_alloc&) throw();
-T     virtual ~bad_alloc() throw();
-T     virtual const char* what() const throw();
-
-
-
-T  new_handler set_new_handler(new_handler new_p) throw();
-
-
-     Header  synopsis
-
-T    class type_info;
-T    class bad_cast;
-T    class bad_typeid;
-
-   18.5.1 - Class type_info [lib.type.info]
-
-T    class type_info {
-    public:
-T      virtual ~type_info();
-T      bool operator==(const type_info& rhs) const;
-T      bool operator!=(const type_info& rhs) const;
-T      bool before(const type_info& rhs) const;
-T      const char* name() const;
-    private:
-T      type_info(const type_info& rhs);
-T      type_info& operator=(const type_info& rhs);
-    };
-
-   18.5.2 - Class bad_cast [lib.bad.cast]
-
-T  bad_cast() throw();
-T  virtual const char* bad_cast::what() const throw();
-
-   18.5.3  Class bad_typeid                              [lib.bad.typeid]
-
-T    class bad_typeid : public exception {
-    public:
-T      bad_typeid() throw();
-T      bad_typeid(const bad_typeid&) throw();
-T      bad_typeid& operator=(const bad_typeid&) throw();
-T      virtual ~bad_typeid() throw();
-T      virtual const char* what() const throw();
-    };
-
-   18.6  Exception handling                       [lib.support.exception]
-
-T      Header  synopsis
-
-T    class exception;
-T    class bad_exception;
-
-T    typedef void (*unexpected_handler)();
-T    unexpected_handler set_unexpected(unexpected_handler f) throw();
-T    void unexpected();
-T    typedef void (*terminate_handler)();
-T    terminate_handler set_terminate(terminate_handler f) throw();
-T    void terminate();
-T    bool uncaught_exception();
-
-   18.6.1  Class exception                                [lib.exception]
-
-T    class exception {
-     public:
-T      exception() throw();
-T      exception(const exception&) throw();
-T      exception& operator=(const exception&) throw();
-T      virtual ~exception() throw();
-T      virtual const char* what() const throw();
-    };
-
-   18.6.2.1  Class bad_exception                      [lib.bad.exception]
-T    class bad_exception : public exception {
-    public:
-T      bad_exception() throw();
-T      bad_exception(const bad_exception&) throw();
-T      bad_exception& operator=(const bad_exception&) throw();
-T      virtual ~bad_exception() throw();
-T      virtual const char* what() const throw();
-    };
-
-   18.7  Other runtime support                      [lib.support.runtime]
-
-   1 Headers  (variable arguments),    (nonlocal  jumps),
-      (system  clock clock(), time()),  (signal handling),
-    and  (runtime environment getenv(), system()).
-
-                    Table 6--Header  synopsis
-                 Macros:   va_arg    va_end   va_start
-X                Type:     va_list
-
-                    Table 7--Header  synopsis
-
-                          Macro:      setjmp |
-X                         Type:       jmp_buf
-                          Function:   longjmp
-
-                     Table 8--Header  synopsis
-
-                      Macros:      CLOCKS_PER_SEC
-X                     Types:       clock_t
-                      Functions:   clock
-
-                    Table 9--Header  synopsis
-
-X        Macros:      SIGABRT        SIGILL   SIGSEGV   SIG_DFL
-         SIG_IGN      SIGFPE         SIGINT   SIGTERM   SIG_ERR
-         Type:        sig_atomic_t
-         Functions:   raise          signal
-
-                   Table 10--Header  synopsis
-
-X                     Functions:   getenv   system
-
-   19.1  Exception classes                           [lib.std.exceptions]
-
-   Header  synopsis
-
-T     class logic_error;
-T     class domain_error;
-T     class invalid_argument;
-T     class length_error;
-T     class out_of_range;
-T     class runtime_error;
-T     class range_error;
-T     class overflow_error;
-T     class underflow_error;
-
-   19.1.1  Class logic_error                            [lib.logic.error]
-T   class logic_error : public exception {
-    public:
-T     explicit logic_error(const string& what_arg);
-    };
-
-   19.1.2  Class domain_error                          [lib.domain.error]
-
-T   class domain_error : public logic_error {
-    public:
-T     explicit domain_error(const string& what_arg);
-    };
-
-   19.1.3  Class invalid_argument                  [lib.invalid.argument]
-
-T   class invalid_argument : public logic_error {
-    public:
-T     explicit invalid_argument(const string& what_arg);
-    };
-
-   19.1.4  Class length_error                          [lib.length.error]
-
-T   class length_error : public logic_error {
-    public:
-T     explicit length_error(const string& what_arg);
-    };
-
-   19.1.5  Class out_of_range                          [lib.out.of.range]
-
-T   class out_of_range : public logic_error {
-    public:
-T     explicit out_of_range(const string& what_arg);
-    };
-
-
-   19.1.6  Class runtime_error                        [lib.runtime.error]
-
-T   class runtime_error : public exception {
-    public:
-T     explicit runtime_error(const string& what_arg);
-    };
-
-
-   19.1.7  Class range_error                            [lib.range.error]
-
-T   class range_error : public runtime_error {
-    public:
-T     explicit range_error(const string& what_arg);
-    };
-
-   19.1.8  Class overflow_error                      [lib.overflow.error]
-
-T   class overflow_error : public runtime_error {
-    public:
-T     explicit overflow_error(const string& what_arg);
-    };
-
-
-   19.1.9  Class underflow_error                    [lib.underflow.error]
-
-T   class underflow_error : public runtime_error {
-    public:
-T     explicit underflow_error(const string& what_arg);
-    };
-
-
-   19.2  Assertions                                      [lib.assertions]
-
-                    Table 2--Header  synopsis
-
-X                         Macro:   assert
-
-   19.3  Error numbers                                        [lib.errno]
-
-                    Table 3--Header  synopsis
-
-X                    |Macros:   EDOM   ERANGE   errno |
-
-
-   20.2  Utility components                                 [lib.utility]
-
-   Header  synopsis
-
-    // _lib.operators_, operators:
-T    namespace rel_ops {
-T      template bool operator!=(const T&, const T&);
-T      template bool operator> (const T&, const T&);
-T      template bool operator<=(const T&, const T&);
-T      template bool operator>=(const T&, const T&);
-    }
-    // _lib.pairs_, pairs:
-T   template  struct pair;
-T   template 
-      bool operator==(const pair&, const pair&);
-T   template 
-      bool operator< (const pair&, const pair&);
-T   template 
-      bool operator!=(const pair&, const pair&);
-T   template 
-      bool operator> (const pair&, const pair&);
-T   template 
-      bool operator>=(const pair&, const pair&);
-T   template 
-      bool operator<=(const pair&, const pair&);
-T   template  pair make_pair(const T1&, const T2&);
-
-
-   20.2.2  Pairs                                              [lib.pairs]
-
-T  template 
-   struct pair {
-T    typedef T1 first_type;
-T    typedef T2 second_type;
-
-T    T1 first;
-T    T2 second;
-T    pair();
-T    pair(const T1& x, const T2& y);
-T    template pair(const pair &p);
-   };
-
-   20.3  Function objects                          [lib.function.objects]
-
-   Header  synopsis
-
-    // _lib.base_, base:
-V   template  struct unary_function;
-V   template  struct binary_function;
-
-    // _lib.arithmetic.operations_, arithmetic operations:
-V   template  struct plus;
-V   template  struct minus;
-V   template  struct multiplies;
-V   template  struct divides;
-V   template  struct modulus;
-V   template  struct negate;
-    // _lib.comparisons_, comparisons:
-V   template  struct equal_to;
-V   template  struct not_equal_to;
-V   template  struct greater;
-V   template  struct less;
-V   template  struct greater_equal;
-V   template  struct less_equal;
-    // _lib.logical.operations_, logical operations:
-V   template  struct logical_and;
-V   template  struct logical_or;
-V   template  struct logical_not;
-    // _lib.negators_, negators:
-    template  struct unary_negate;
-V   template 
-      unary_negate  not1(const Predicate&);
-V   template  struct binary_negate;
-V   template 
-      binary_negate not2(const Predicate&);
-    // _lib.binders_, binders:
-V   template   class binder1st;
-V   template 
-      binder1st bind1st(const Operation&, const T&);
-V   template  class binder2nd;
-V   template 
-      binder2nd bind2nd(const Operation&, const T&);
-    // _lib.function.pointer.adaptors_, adaptors:
-V   template  class pointer_to_unary_function;
-V   template 
-      pointer_to_unary_function ptr_fun(Result (*)(Arg));
-V   template 
-      class pointer_to_binary_function;
-V   template 
-      pointer_to_binary_function
-        ptr_fun(Result (*)(Arg1,Arg2));
-
-    // _lib.member.pointer.adaptors_, adaptors:
-V   template class mem_fun_t;
-V   template class mem_fun1_t;
-V   template
-        mem_fun_t mem_fun(S (T::*f)());
-V   template
-        mem_fun1_t mem_fun(S (T::*f)(A));
-V   template class mem_fun_ref_t;
-V   template class mem_fun1_ref_t;
-V   template
-        mem_fun_ref_t mem_fun_ref(S (T::*f)());
-V   template
-        mem_fun1_ref_t mem_fun_ref(S (T::*f)(A));
-
-V   template  class const_mem_fun_t;
-V   template  class const_mem_fun1_t;
-V   template 
-      const_mem_fun_t mem_fun(S (T::*f)() const);
-V   template 
-      const_mem_fun1_t mem_fun(S (T::*f)(A) const);
-V   template  class const_mem_fun_ref_t;
-V   template  class const_mem_fun1_ref_t;
-V   template 
-      const_mem_fun_ref_t mem_fun_ref(S (T::*f)() const);
-V   template 
-      const_mem_fun1_ref_t mem_fun_ref(S (T::*f)(A) const);
-   }
-
-   20.3.1  Base                                                [lib.base]
-
-V   template 
-    struct unary_function {
-V     typedef Arg    argument_type;
-V     typedef Result result_type;
-    };
-V   template 
-    struct binary_function {
-V     typedef Arg1   first_argument_type;
-V     typedef Arg2   second_argument_type;
-V     typedef Result result_type;
-    };
-
-   20.3.2  Arithmetic operations              [lib.arithmetic.operations]
-
-T  template  struct plus : binary_function {
-V   T operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct minus : binary_function {
-V   T operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct multiplies : binary_function {
-V   T operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct divides : binary_function {
-V   T operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct modulus : binary_function {
-V   T operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct negate : unary_function {
-V   T operator()(const T& x) const;
-   };
-
-   20.3.3  Comparisons                                  [lib.comparisons]
-
-T  template  struct equal_to : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct not_equal_to : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct greater : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct less : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct greater_equal : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct less_equal : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-   20.3.4  Logical operations                    [lib.logical.operations]
-
-T  template  struct logical_and : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct logical_or : binary_function {
-V   bool operator()(const T& x, const T& y) const;
-   };
-
-T  template  struct logical_not : unary_function {
-V   bool operator()(const T& x) const;
-   };
-
-   20.3.5  Negators                                        [lib.negators]
-
-T  template 
-    class unary_negate
-      : public unary_function {
-   public:
-T   explicit unary_negate(const Predicate& pred);
-V   bool operator()(const typename Predicate::argument_type& x) const;
-   };
-
-T  template 
-    class binary_negate
-      : public binary_function {
-    public:
-T     explicit binary_negate(const Predicate& pred);
-V     bool operator()(const typename Predicate::first_argument_type&  x,
-          const typename Predicate::second_argument_type& y) const;
-    };
-
-
-   20.3.6  Binders                                          [lib.binders]
-
-   20.3.6.1  Template class binder1st                    [lib.binder.1st]
-T   template 
-    class binder1st
-      : public unary_function {
-    protected:
-T     Operation                      op;
-T     typename Operation::first_argument_type value;
-    public:
-V     binder1st(const Operation& x,
-                const typename Operation::first_argument_type& y);
-V     typename Operation::result_type
-        operator()(const typename Operation::second_argument_type& x) const;
-    };
-
-   20.3.6.2  bind1st                                       [lib.bind.1st]
-
-V  template 
-    binder1st bind1st(const Operation& op, const T& x);
-
-   20.3.6.3  Template class binder2nd                    [lib.binder.2nd]
-T   template 
-    class binder2nd
-      : public unary_function {
-    protected:
-T     Operation                       op;
-T     typename Operation::second_argument_type value;
-    public:
-V     binder2nd(const Operation& x,
-                const typename Operation::second_argument_type& y);
-V     typename Operation::result_type
-        operator()(const typename Operation::first_argument_type& x) const;
-    };
-
-   20.3.6.4  bind2nd                                       [lib.bind.2nd]
-
-T  template 
-    binder2nd bind2nd(const Operation& op, const T& x);
-
-
-   20.3.7  Adaptors for pointers to       [lib.function.pointer.adaptors]
-       functions
-
-   1 To  allow  pointers to (unary and binary) functions to work with func-
-   tion adaptors the library provides:
-
-T   template 
-    class pointer_to_unary_function : public unary_function {
-    public:
-T     explicit pointer_to_unary_function(Result (*f)(Arg));
-V     Result operator()(Arg x) const;
-    };
-
-T  template 
-    pointer_to_unary_function ptr_fun(Result (*f)(Arg));
-
-T       template 
-        class pointer_to_binary_function :
-          public binary_function {
-        public:
-T         explicit pointer_to_binary_function(Result (*f)(Arg1, Arg2));
-V         Result operator()(Arg1 x, Arg2 y) const;
-        };
-
-
-   20.3.8  Adaptors for pointers to         [lib.member.pointer.adaptors]
-       members
-
-T  template  class mem_fun_t
-          : public unary_function {
-   public:
-T   explicit mem_fun_t(S (T::*p)());
-V   S operator()(T* p) const;
-   };
-
-T   template  class mem_fun1_t
-          : public binary_function {
-    public:
-T     explicit mem_fun1_t(S (T::*p)(A));
-V     S operator()(T* p, A x) const;
-   };
-
-V   template mem_fun_t
-       mem_fun(S (T::*f)());
-V   template mem_fun1_t
-       mem_fun(S (T::*f)(A));
-
-T   template  class mem_fun_ref_t
-          : public unary_function {
-    public:
-T     explicit mem_fun_ref_t(S (T::*p)());
-V     S operator()(T& p) const;
-   };
-
-T   template  class mem_fun1_ref_t
-          : public binary_function {
-    public:
-T     explicit mem_fun1_ref_t(S (T::*p)(A));
-V     S operator()(T& p, A x) const;
-   };
-
-T   template mem_fun_ref_t
-       mem_fun_ref(S (T::*f)());
-
-T   template mem_fun1_ref_t
-       mem_fun_ref(S (T::*f)(A));
-
-T  template  class const_mem_fun_t
-        : public unary_function {
-   public:
-T   explicit const_mem_fun_t(S (T::*p)() const);
-V   S operator()(const T* p) const;
-   };
-
-T  template  class const_mem_fun1_t
-        : public binary_function {
-   public:
-T   explicit const mem_fun1_t(S (T::*p)(A) const);
-V   S operator()(const T* p, A x) const;
-   };
-
-V   template const_mem_fun_t
-       mem_fun(S (T::*f)() const);
-V   template const_mem_fun1_t
-       mem_fun(S (T::*f)(A) const);
-
-T   template  class const_mem_fun_ref_t
-          : public unary_function {
-    public:
-T     explicit const_mem_fun_ref_t(S (T::*p)() const);
-V     S operator()(const T& p) const;
-   };
-
-T   template  class const_mem_fun1_ref_t
-          : public binary_function {
-    public:
-T     explicit const_mem_fun1_ref_t(S (T::*p)(A) const);
-V     S operator()(const T& p, A x) const;
-   };
-
-T   template const_mem_fun_ref_t
-       mem_fun_ref(S (T::*f)() const);
-
-T   template const_mem_fun1_ref_t
-        mem_fun_ref(S (T::*f)(A) const);
-
-   20.4  Memory                                              [lib.memory]
-
-   Header  synopsis
-
-    // _lib.default.allocator_, the default allocator:
-T   template  class allocator;
-T   template <> class allocator;
-T   template 
-      bool operator==(const allocator&, const allocator&) throw();
-T   template 
-      bool operator!=(const allocator&, const allocator&) throw();
-    // _lib.storage.iterator_, raw storage iterator:
-T   template  class raw_storage_iterator;
-    // _lib.temporary.buffer_, temporary buffers:
-T   template 
-      pair get_temporary_buffer(ptrdiff_t n);
-T   template 
-      void return_temporary_buffer(T* p);
-    // _lib.specialized.algorithms_, specialized algorithms:
-T   template 
-      ForwardIterator
-        uninitialized_copy(InputIterator first, InputIterator last,
-                           ForwardIterator result);
-T   template 
-      void uninitialized_fill(ForwardIterator first, ForwardIterator last,
-                              const T& x);
-T   template 
-      void uninitialized_fill_n(ForwardIterator first, Size n, const T& x);
-    // _lib.auto.ptr_, pointers:
-X   template class auto_ptr;
-   }
-
-   20.4.1  The default allocator                  [lib.default.allocator]
-
-T   template  class allocator;
-    // specialize for void:
-T   template <> class allocator {
-    public:
-T     typedef void*       pointer;
-T     typedef const void* const_pointer;
-      // reference-to-void members are impossible.
-T     typedef void  value_type;
-T     template  struct rebind { typedef allocator other; };
-    };
-
-T   template  class allocator {
-     public:
-T     typedef size_t    size_type;
-T     typedef ptrdiff_t difference_type;
-T     typedef T*        pointer;
-T     typedef const T*  const_pointer;
-T     typedef T&        reference;
-T     typedef const T&  const_reference;
-T     typedef T         value_type;
-T     template  struct rebind { typedef allocator other; };
-T     allocator() throw();
-T     allocator(const allocator&) throw();
-T     template  allocator(const allocator&) throw();
-T    ~allocator() throw();
-T     pointer address(reference x) const;
-T     const_pointer address(const_reference x) const;
-T     pointer allocate(
-        size_type, allocator::const_pointer hint = 0);
-T     void deallocate(pointer p, size_type n);
-T     size_type max_size() const throw();
-T     void construct(pointer p, const T& val);
-T     void destroy(pointer p);
-    };
-
-   20.4.1.2  allocator globals                    [lib.allocator.globals]
-
-T  template 
-    bool operator==(const allocator&, const allocator&) throw();
-T  template 
-    bool operator!=(const allocator&, const allocator&) throw();
-
-   20.4.2  Raw storage iterator                    [lib.storage.iterator]
-
-T   template 
-    class raw_storage_iterator
-      : public iterator {
-    public:
-T     explicit raw_storage_iterator(OutputIterator x);
-T     raw_storage_iterator& operator*();
-T     raw_storage_iterator& operator=(const T& element);
-T     raw_storage_iterator& operator++();
-T     raw_storage_iterator  operator++(int);
-    };
-
-   20.4.3  Temporary buffers                       [lib.temporary.buffer]
-
-T  template 
-    pair get_temporary_buffer(ptrdiff_t n);
-
-T  template  void return_temporary_buffer(T* p);
-
-   20.4.4  Specialized algorithms            [lib.specialized.algorithms]
-
-   20.4.4.1  uninitialized_copy                  [lib.uninitialized.copy]
-
-V  template 
-    ForwardIterator
-      uninitialized_copy(InputIterator first, InputIterator last,
-                         ForwardIterator result);
-
-   20.4.4.2  uninitialized_fill                  [lib.uninitialized.fill]
-
-V  template 
-    void uninitialized_fill(ForwardIterator first, ForwardIterator last,
-                            const T& x);
-
-   20.4.4.3  uninitialized_fill_n              [lib.uninitialized.fill.n]
-
-V  template 
-    void uninitialized_fill_n(ForwardIterator first, Size n, const T& x);
-
-   20.4.5  Template class auto_ptr                         [lib.auto.ptr]
-
-X   template class auto_ptr {
-      template  struct auto_ptr_ref {};
-    public:
-T     typedef X element_type;
-      // _lib.auto.ptr.cons_ construct/copy/destroy:
-T     explicit auto_ptr(X* p =0) throw();
-T     auto_ptr(auto_ptr&) throw();
-T     template auto_ptr(auto_ptr&) throw();
-T     auto_ptr& operator=(auto_ptr&) throw();
-T     template auto_ptr& operator=(auto_ptr&) throw();
-T    ~auto_ptr() throw();
-      // _lib.auto.ptr.members_ members:
-T     X& operator*() const throw();
-T     X* operator->() const throw();
-T     X* get() const throw();
-T     X* release() throw();
-T     void reset(X* p =0) throw();
-
-      // _lib.auto.ptr.conv_ conversions:
-X     auto_ptr(auto_ptr_ref) throw();
-X     template operator auto_ptr_ref() throw();
-X     template operator auto_ptr() throw();
-    };
-
-   20.4.6  C Library                                       [lib.c.malloc]
-
-                    Table 7--Header  synopsis
-
-X                    Functions:   calloc   malloc
-                                  free     realloc
-
-
-                    Table 8--Header  synopsis
-
-X                    Macro:       NULL
-X                    Type:        size_t
-X                    Functions:   memchr    memcmp
-X                    memcpy       memmove   memset
-
-                     Table 9--Header  synopsis
-
-X          Macros:   NULL
-X          Types:    size_t   clock_t    time_t
-X          Struct:   tm
-           Functions:
-X          asctime   clock    difftime   localtime   strftime
-X          ctime     gmtime   mktime     time
-
-   21.1.1  Character traits requirements        [lib.char.traits.require]
-
-   2 The struct template
-T  template struct char_traits;
-   shall be provided in the header  as a basis for  explicit spe-
-   cializations.
-
-
-   21.1.3.1  struct                [lib.char.traits.specializations.char]
-       char_traits
-
-T   template<>
-    struct char_traits {
-T     typedef char        char_type;
-T     typedef int         int_type;
-T     typedef streamoff   off_type;
-T     typedef streampos   pos_type;
-T     typedef mbstate_t   state_type;
-
-T     static void assign(char_type& c1, const char_type& c2);
-T     static bool eq(const char_type& c1, const char_type& c2);
-T     static bool lt(const char_type& c1, const char_type& c2);
-
-T     static int compare(const char_type* s1, const char_type* s2, size_t n);
-T     static size_t length(const char_type* s);
-T     static const char_type* find(const char_type* s, size_t n,
-                                   const char_type& a);
-T     static char_type* move(char_type* s1, const char_type* s2, size_t n);
-T     static char_type* copy(char_type* s1, const char_type* s2, size_t n);
-T     static char_type* assign(char_type* s, size_t n, char_type a);
-
-T     static int_type not_eof(const int_type& c);
-T     static char_type to_char_type(const int_type& c);
-T     static int_type to_int_type(const char_type& c);
-T     static bool eq_int_type(const int_type& c1, const int_type& c2);
-T     static int_type eof();
-    };
-
-   21.1.3.2  struct             [lib.char.traits.specializations.wchar.t]
-       char_traits
-
-V   template<>
-    struct char_traits {
-V     typedef wchar_t      char_type;
-V     typedef wint_t       int_type;
-V     typedef streamoff   off_type;
-V     typedef wstreampos   pos_type;
-V     typedef mbstate_t    state_type;
-
-V     static void assign(char_type& c1, const char_type& c2);
-V     static bool eq(const char_type& c1, const char_type& c2);
-V     static bool lt(const char_type& c1, const char_type& c2);
-
-V     static int compare(const char_type* s1, const char_type* s2, size_t n);
-V     static size_t length(const char_type* s);
-V     static const char_type* find(const char_type* s, size_t n,
-                                   const char_type& a);
-V     static char_type* move(char_type* s1, const char_type* s2, size_t n);
-V     static char_type* copy(char_type* s1, const char_type* s2, size_t n);
-V     static char_type* assign(char_type* s, size_t n, char_type a);
-
-V     static int_type not_eof(const int_type& c);
-V     static char_type to_char_type(const int_type& c);
-V     static int_type to_int_type(const char_type& c);
-V     static bool eq_int_type(const int_type& c1, const int_type& c2);
-V     static int_type eof();
-    };
-
-   21.2  String classes                              [lib.string.classes]
-
-    // _lib.char.traits_, character traits:
-V   template
-      struct char_traits;
-V   template <> struct char_traits;
-V   template <> struct char_traits;
-
-    // _lib.basic.string_, basic_string:
-V   template,
-             class Allocator = allocator >
-      class basic_string;
-V   template
-      basic_string
-        operator+(const basic_string& lhs,
-                  const basic_string& rhs);
-V   template
-      basic_string
-        operator+(const charT* lhs,
-                  const basic_string& rhs);
-V   template
-      basic_string
-        operator+(charT lhs, const basic_string& rhs);
-V   template
-      basic_string
-        operator+(const basic_string& lhs,
-                  const charT* rhs);
-V   template
-      basic_string
-        operator+(const basic_string& lhs, charT rhs);
-
-V   template
-      bool operator==(const basic_string& lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator==(const charT* lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator==(const basic_string& lhs,
-                      const charT* rhs);
-V   template
-      bool operator!=(const basic_string& lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator!=(const charT* lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator!=(const basic_string& lhs,
-                      const charT* rhs);
-V   template
-      bool operator< (const basic_string& lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator< (const basic_string& lhs,
-                      const charT* rhs);
-V   template
-      bool operator< (const charT* lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator> (const basic_string& lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator> (const basic_string& lhs,
-                      const charT* rhs);
-V   template
-      bool operator> (const charT* lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator<=(const basic_string& lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator<=(const basic_string& lhs,
-                      const charT* rhs);
-V   template
-      bool operator<=(const charT* lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator>=(const basic_string& lhs,
-                      const basic_string& rhs);
-V   template
-      bool operator>=(const basic_string& lhs,
-                      const charT* rhs);
-V   template
-      bool operator>=(const charT* lhs,
-                      const basic_string& rhs);
-
-    // _lib.string.special_:
-V   template
-       void swap(basic_string& lhs,
-                 basic_string& rhs);
-V   template
-     basic_istream&
-      operator>>(basic_istream& is,
-                 basic_string& str);
-T   template
-     basic_ostream&
-      operator<<(basic_ostream& os,
-                 const basic_string& str);
-V   template
-     basic_istream&
-       getline(basic_istream& is,
-               basic_string& str,
-               charT delim);
-V   template
-     basic_istream&
-       getline(basic_istream& is,
-               basic_string& str);
-V   typedef basic_string string;
-T   typedef basic_string wstring;
-   }
-
-   21.3  Template class basic_string                   [lib.basic.string]
-
-V  namespace std {
-    template,
-             class Allocator = allocator >
-    class basic_string {
-    public:
-      // types:
-      typedef          traits                     traits_type;
-      typedef typename traits::char_type          value_type;
-      typedef          Allocator                  allocator_type;
-      typedef typename Allocator::size_type       size_type;
-      typedef typename Allocator::difference_type difference_type;
-      typedef typename Allocator::reference       reference;
-      typedef typename Allocator::const_reference const_reference;
-      typedef typename Allocator::pointer         pointer;
-      typedef typename Allocator::const_pointer   const_pointer;
-      typedef implementation defined             iterator;
-      typedef implementation defined             const_iterator;
-      typedef std::reverse_iterator reverse_iterator;
-      typedef std::reverse_iterator const_reverse_iterator;
-      static const size_type npos = -1;
-
-      // _lib.string.cons_ construct/copy/destroy:
-V     explicit basic_string(const Allocator& a = Allocator());
-V     basic_string(const basic_string& str, size_type pos = 0,
-                   size_type n = npos, const Allocator& a = Allocator());
-V     basic_string(const charT* s,
-                   size_type n, const Allocator& a = Allocator());
-V     basic_string(const charT* s, const Allocator& a = Allocator());
-V     basic_string(size_type n, charT c, const Allocator& a = Allocator());
-V     template
-        basic_string(InputIterator begin, InputIterator end,
-                     const Allocator& a = Allocator());
-V    ~basic_string();
-V     basic_string& operator=(const basic_string& str);
-V     basic_string& operator=(const charT* s);
-V     basic_string& operator=(charT c);
-      // _lib.string.iterators_ iterators:
-V     iterator       begin();
-V     const_iterator begin() const;
-V     iterator       end();
-V     const_iterator end() const;
-
-V     reverse_iterator       rbegin();
-V     const_reverse_iterator rbegin() const;
-V     reverse_iterator       rend();
-V     const_reverse_iterator rend() const;
-      // _lib.string.capacity_ capacity:
-V     size_type size() const;
-V     size_type length() const;
-V     size_type max_size() const;
-V     void resize(size_type n, charT c);
-V     void resize(size_type n);
-V     size_type capacity() const;
-V     void reserve(size_type res_arg = 0);
-V     void clear();
-V     bool empty() const;
-      // _lib.string.access_ element access:
-V     const_reference operator[](size_type pos) const;
-V     reference       operator[](size_type pos);
-V     const_reference at(size_type n) const;
-V     reference       at(size_type n);
-      // _lib.string.modifiers_ modifiers:
-V     basic_string& operator+=(const basic_string& str);
-V     basic_string& operator+=(const charT* s);
-V     basic_string& operator+=(charT c);
-V     basic_string& append(const basic_string& str);
-V     basic_string& append(const basic_string& str, size_type pos,
-                           size_type n);
-V     basic_string& append(const charT* s, size_type n);
-V     basic_string& append(const charT* s);
-V     basic_string& append(size_type n, charT c);
-V     template
-        basic_string& append(InputIterator first, InputIterator last);
-V     void push_back(const charT);
-
-V     basic_string& assign(const basic_string&);
-V     basic_string& assign(const basic_string& str, size_type pos,
-                           size_type n);
-V     basic_string& assign(const charT* s, size_type n);
-V     basic_string& assign(const charT* s);
-V     basic_string& assign(size_type n, charT c);
-V     template
-        basic_string& assign(InputIterator first, InputIterator last);
-V     basic_string& insert(size_type pos1, const basic_string& str);
-V     basic_string& insert(size_type pos1, const basic_string& str,
-                           size_type pos2, size_type n);
-V     basic_string& insert(size_type pos, const charT* s, size_type n);
-V     basic_string& insert(size_type pos, const charT* s);
-V     basic_string& insert(size_type pos, size_type n, charT c);
-V     iterator insert(iterator p, charT c);
-V     void     insert(iterator p, size_type n, charT c);
-V     template
-        void insert(iterator p, InputIterator first, InputIterator last);
-V     basic_string& erase(size_type pos = 0, size_type n = npos);
-V     iterator erase(iterator position);
-V     iterator erase(iterator first, iterator last);
-V     basic_string& replace(size_type pos1, size_type n1,
-                            const basic_string& str);
-V     basic_string& replace(size_type pos1, size_type n1,
-                            const basic_string& str,
-                            size_type pos2, size_type n2);
-V     basic_string& replace(size_type pos, size_type n1, const charT* s,
-                            size_type n2);
-V     basic_string& replace(size_type pos, size_type n1, const charT* s);
-V     basic_string& replace(size_type pos, size_type n1, size_type n2,
-                            charT c);
-V     basic_string& replace(iterator i1, iterator i2, const basic_string& str);
-V     basic_string& replace(iterator i1, iterator i2, const charT* s,
-                            size_type n);
-V     basic_string& replace(iterator i1, iterator i2, const charT* s);
-V     basic_string& replace(iterator i1, iterator i2,
-                            size_type n, charT c);
-V     template
-        basic_string& replace(iterator i1, iterator i2,
-                              InputIterator j1, InputIterator j2);
-V     size_type copy(charT* s, size_type n, size_type pos = 0) const;
-V     void swap(basic_string&);
-      // _lib.string.ops_ string operations:
-V     const charT* c_str() const;         // explicit
-V     const charT* data() const;
-V     allocator_type get_allocator() const;
-V     size_type find (const basic_string& str, size_type pos = 0) const;
-V     size_type find (const charT* s, size_type pos, size_type n) const;
-V     size_type find (const charT* s, size_type pos = 0) const;
-V     size_type find (charT c, size_type pos = 0) const;
-V     size_type rfind(const basic_string& str, size_type pos = npos) const;
-V     size_type rfind(const charT* s, size_type pos, size_type n) const;
-V     size_type rfind(const charT* s, size_type pos = npos) const;
-V     size_type rfind(charT c, size_type pos = npos) const;
-
-V     size_type find_first_of(const basic_string& str,
-                              size_type pos = 0) const;
-V     size_type find_first_of(const charT* s,
-                              size_type pos, size_type n) const;
-V     size_type find_first_of(const charT* s, size_type pos = 0) const;
-V     size_type find_first_of(charT c, size_type pos = 0) const;
-V     size_type find_last_of (const basic_string& str,
-                              size_type pos = npos) const;
-V     size_type find_last_of (const charT* s,
-                              size_type pos, size_type n) const;
-V     size_type find_last_of (const charT* s, size_type pos = npos) const;
-V     size_type find_last_of (charT c, size_type pos = npos) const;
-V     size_type find_first_not_of(const basic_string& str,
-                                  size_type pos = 0) const;
-V     size_type find_first_not_of(const charT* s, size_type pos,
-                                  size_type n) const;
-V     size_type find_first_not_of(const charT* s, size_type pos = 0) const;
-V     size_type find_first_not_of(charT c, size_type pos = 0) const;
-V     size_type find_last_not_of (const basic_string& str,
-                                  size_type pos = npos) const;
-V     size_type find_last_not_of (const charT* s, size_type pos,
-                                  size_type n) const;
-V     size_type find_last_not_of (const charT* s,
-                                  size_type pos = npos) const;
-V     size_type find_last_not_of (charT c, size_type pos = npos) const;
-V     basic_string substr(size_type pos = 0, size_type n = npos) const;
-V     int compare(const basic_string& str) const;
-V     int compare(size_type pos1, size_type n1,
-                  const basic_string& str) const;
-V     int compare(size_type pos1, size_type n1,
-                  const basic_string& str,
-                  size_type pos2, size_type n2) const;
-V     int compare(const charT* s) const;
-V     int compare(size_type pos1, size_type n1,
-                  const charT* s, size_type n2 = npos) const;
-    };
-   }
-
-   21.4  Null-terminated sequence utilities               [lib.c.strings]
-
-                    Table 10--Header  synopsis
-
-            isalnum   isdigit   isprint   isupper    tolower
-X           isalpha   isgraph   ispunct   isxdigit   toupper
-            iscntrl   islower   isspace
-
-                   Table 11--Header  synopsis
-
-X  Macro:     WEOF 
-X  Types:     wctrans_t   wctype_t   wint_t 
-   Functions:
-X  iswalnum   iswctype    iswlower   iswspace    towctrans   wctrans
-X  iswalpha   iswdigit    iswprint   iswupper    towlower    wctype
-X  iswcntrl   iswgraph    iswpunct   iswxdigit   towupper
-
-                   Table 12--Header  synopsis
-
-X           Macro:    NULL 
-X           Type:     size_t 
-            Functions:
-X           memchr    strcat    strcspn    strncpy   strtok
-X           memcmp    strchr    strerror   strpbrk   strxfrm
-X           memcpy    strcmp    strlen     strrchr
-X           memmove   strcoll   strncat    strspn
-X           memset    strcpy    strncmp    strstr
-
-                    Table 13--Header  synopsis
-   Macros:    NULL    WCHAR_MAX         WCHAR_MIN   WEOF 
-   Types:     mbstate_t       wint_t    size_t
-   Functions:
-X  btowc      getwchar        ungetwc           wcscpy      wcsrtombs   wmemchr
-X  fgetwc     mbrlen          vfwprintf         wcscspn     wcsspn      wmemcmp
-X  fgetws     mbrtowc         vswprintf         wcsftime    wcsstr      wmemcpy
-X  fputwc     mbsinit         vwprintf          wcslen      wcstod      wmemmove
-X  fputws     mbsrtowcs       wcrtomb           wcsncat     wcstok      wmemset
-X  fwide      putwc           wcscat            wcsncmp     wcstol      wprintf
-X  fwprintf   putwchar        wcschr            wcsncpy     wcstoul     wscanf
-X  fwscanf    swprintf        wcscmp            wcspbrk     wcsxfrm
-X  getwc      swscanf         wcscoll           wcsrchr     wctob
-
-                   Table 14--Header  synopsis
-
-               Macros:   MB_CUR_MAX
-               Functions:
-X              atol      mblen        strtod    wctomb
-X              atof      mbstowcs     strtol    wcstombs
-X              atoi      mbtowc       strtoul
-
-X  const char* strchr(const char* s, int c);
-X       char* strchr(      char* s, int c);
-
-X  const char* strpbrk(const char* s1, const char* s2);
-X       char* strpbrk(      char* s1, const char* s2);
-
-X  const char* strrchr(const char* s, int c);
-X       char* strrchr(      char* s, int c);
-
-X  const char* strstr(const char* s1, const char* s2);
-X       char* strstr(      char* s1, const char* s2);
-
-X  const void* memchr(const void* s, int c, size_t n);
-X       void* memchr(      void* s, int c, size_t n);
-
-X  const wchar_t* wcschr(const wchar_t* s, wchar_t c);
-X       wchar_t* wcschr(      wchar_t* s, wchar_t c);
-
-X  const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2);
-X       wchar_t* wcspbrk(      wchar_t* s1, const wchar_t* s2);
-
-X  const wchar_t* wcsrchr(const wchar_t* s, wchar_t c);
-X       wchar_t* wcsrchr(      wchar_t* s, wchar_t c);
-
-X  const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2);
-X       wchar_t* wcsstr(      wchar_t* s1, const wchar_t* s2);
-
-X  const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n);
-X       wchar_t* wmemchr(      wchar_t* s, wchar_t c, size_t n);
-
-   [for initial efforts on the above, see shadow/string.h]
-
-   22.1  Locales                                            [lib.locales]
-
-   Header  synopsis
-
-    // _lib.locale_, locale:
-T   class locale;
-T   template  const Facet& use_facet(const locale&);
-T   template  bool         has_facet(const locale&) throw();
-
-    // _lib.locale.convenience_, convenience interfaces:
-T   template  bool isspace (charT c, const locale& loc);
-T   template  bool isprint (charT c, const locale& loc);
-T   template  bool iscntrl (charT c, const locale& loc);
-T   template  bool isupper (charT c, const locale& loc);
-T   template  bool islower (charT c, const locale& loc);
-T   template  bool isalpha (charT c, const locale& loc);
-T   template  bool isdigit (charT c, const locale& loc);
-T   template  bool ispunct (charT c, const locale& loc);
-T   template  bool isxdigit(charT c, const locale& loc);
-T   template  bool isalnum (charT c, const locale& loc);
-T   template  bool isgraph (charT c, const locale& loc);
-T   template  charT toupper(charT c, const locale& loc);
-T   template  charT tolower(charT c, const locale& loc);
-    // _lib.category.ctype_ and _lib.facet.ctype.special_, ctype:
-    class ctype_base;
-T   template  class ctype;
-T   template <>            class ctype;             // specialization
-S   template  class ctype_byname;
-S   template <>            class ctype_byname;      // specialization
-T   class codecvt_base;
-X   template  class codecvt;
-S   template  class codecvt_byname;
-    // _lib.category.numeric_ and _lib.facet.numpunct_, numeric:
-X   template   class num_get;
-X   template  class num_put;
-T   template  class numpunct;
-S   template  class numpunct_byname;
-    // _lib.category.collate_, collation:
-T   template  class collate;
-S   template  class collate_byname;
-    // _lib.category.time_, date and time:
-T   class time_base;
-S   template   class time_get;
-S   template   class time_get_byname;
-S   template  class time_put;
-S   template  class time_put_byname;
-    // _lib.category.monetary_, money:
-T   class money_base;
-S   template   class money_get;
-S   template  class money_put;
-S   template  class moneypunct;
-S   template  class moneypunct_byname;
-    // _lib.category.messages_, message retrieval:
-T   class messages_base;
-S   template  class messages;
-S   template  class messages_byname;
-
-
-   22.1.1  Class locale                                      [lib.locale]
-
-X   class locale {
-    public:
-      // types:
-T     class facet;
-T     class id;
-T     typedef int category;
-T     static const category   // values assigned here are for exposition only
-T       none     = 0,
-T       collate  = 0x010, ctype    = 0x020,
-T       monetary = 0x040, numeric  = 0x080,
-T       time     = 0x100, messages = 0x200,
-T       all = collate | ctype | monetary | numeric | time  | messages;
-      // construct/copy/destroy:
-T     locale() throw()
-T     locale(const locale& other) throw()
-X     explicit locale(const char* std_name);
-X     locale(const locale& other, const char* std_name, category);
-T     template  locale(const locale& other, Facet* f);
-T     locale(const locale& other, const locale& one, category);
-T    ~locale() throw();           // non-virtual
-T     const locale& operator=(const locale& other) throw();
-T     template  locale combine(const locale& other) const;
-      // locale operations:
-X     basic_string                  name() const;
-T     bool operator==(const locale& other) const;
-T     bool operator!=(const locale& other) const;
-T     template 
-        bool operator()(const basic_string& s1,
-                        const basic_string& s2) const;
-      // global locale objects:
-T     static       locale  global(const locale&);
-T     static const locale& classic();
-    };
-
-   22.1.1.1  locale types                              [lib.locale.types]
-
-   22.1.1.1.1  Type locale::category                [lib.locale.category]
-
-T  typedef int category;
-
-T   none, collate, ctype, monetary, numeric, time, and messages
-
-      [required locale members]
-T     collate, collate
-T     ctype, ctype
-T     codecvt,
-S     codecvt
-T     moneypunct, moneypunct
-T     moneypunct, moneypunct,
-S     money_get, money_get, money_put
-T     numpunct, numpunct,
-X     num_get, num_get
-X     num_put, num_put
-S     time_get, time_get,
-S     time_put, time_put
-S     messages, messages
-
-      [required instantiations]
-S    collate_byname, collate_byname
-S    ctype_byname, ctype_byname
-S    codecvt_byname,
-S    codecvt_byname
-S    moneypunct_byname,
-S    moneypunct_byname,
-S    money_get,
-S    money_put
-S    numpunct_byname, numpunct_byname
-X    num_get, num_put
-S    time_get,
-S    time_get_byname,
-S    time_get,
-S    time_get_byname,
-S    time_put,
-S    time_put_byname,
-S    time_put
-S    time_put_byname
-S    messages_byname, messages_byname
-
-
-   22.1.1.1.2  Class locale::facet                     [lib.locale.facet]
-
-T   class locale::facet {
-    protected:
-T     explicit facet(size_t refs = 0);
-T     virtual ~facet();
-    private:
-T     facet(const facet&);                // not defined
-T     void operator=(const facet&);       // not defined
-    };
-   }
-
-
-   22.1.1.1.3  Class locale::id                           [lib.locale.id]
-
-T   class locale::id {
-    public:
-T     id();
-    private:
-T     void operator=(const id&);  // not defined
-T     id(const id&);              // not defined
-    };
-   }
-
-
-   22.2.1  The ctype category                        [lib.category.ctype]
-
-T   class ctype_base {
-    public:
-T     enum mask {         // numeric values are for exposition only.
-T       space=, print=, cntrl=, upper=, lower=,
-T       alpha=, digit=, punct=, xdigit=,
-T       alnum=, graph=
-      };
-    };
-
-
-   22.2.1.1  Template class ctype                      [lib.locale.ctype]
-
-T   template 
-    class ctype : public locale::facet, public ctype_base {
-    public:
-T     typedef charT char_type;
-T     explicit ctype(size_t refs = 0);
-T     bool         is(mask m, charT c) const;
-T     const charT* is(const charT* low, const charT* high, mask* vec) const;
-T     const charT* scan_is(mask m,
-                           const charT* low, const charT* high) const;
-T     const charT* scan_not(mask m,
-                            const charT* low, const charT* high) const;
-T     charT        toupper(charT c) const;
-T     const charT* toupper(charT* low, const charT* high) const;
-T     charT        tolower(charT c) const;
-T     const charT* tolower(charT* low, const charT* high) const;
-T     charT        widen(char c) const;
-T     const char*  widen(const char* low, const char* high, charT* to) const;
-T     char         narrow(charT c, char dfault) const;
-T     const charT* narrow(const charT* low, const charT*, char dfault,
-                          char* to) const;
-T     static locale::id id;
-
-    protected:
-T    ~ctype();                    // virtual
-T     virtual bool         do_is(mask m, charT c) const;
-T     virtual const charT* do_is(const charT* low, const charT* high,
-                                 mask* vec) const;
-T     virtual const charT* do_scan_is(mask m,
-                              const charT* low, const charT* high) const;
-T     virtual const charT* do_scan_not(mask m,
-                              const charT* low, const charT* high) const;
-T     virtual charT        do_toupper(charT) const;
-T     virtual const charT* do_toupper(charT* low, const charT* high) const;
-T     virtual charT        do_tolower(charT) const;
-T     virtual const charT* do_tolower(charT* low, const charT* high) const;
-T     virtual charT        do_widen(char) const;
-T     virtual const char*  do_widen(const char* low, const char* high,
-                                    charT* dest) const;
-T     virtual char         do_narrow(charT, char dfault) const;
-T     virtual const charT* do_narrow(const charT* low, const charT* high,
-                                     char dfault, char* dest) const;
-    };
-
-
-   22.2.1.2  Template class ctype_byname        [lib.locale.ctype.byname]
-
-X   template 
-    class ctype_byname : public ctype {
-    public:
-T     typedef ctype::mask mask;
-S     explicit ctype_byname(const char*, size_t refs = 0);
-    protected:
-S    ~ctype_byname();             // virtual
-S     virtual bool         do_is(mask m, charT c) const;
-S     virtual const charT* do_is(const charT* low, const charT* high,
-                                 mask* vec) const;
-S     virtual const char*  do_scan_is(mask m,
-                               const charT* low, const charT* high) const;
-S     virtual const char*  do_scan_not(mask m,
-                               const charT* low, const charT* high) const;
-S     virtual charT        do_toupper(charT) const;
-S     virtual const charT* do_toupper(charT* low, const charT* high) const;
-S     virtual charT        do_tolower(charT) const;
-S     virtual const charT* do_tolower(charT* low, const charT* high) const;
-S     virtual charT        do_widen(char) const;
-S     virtual const char*  do_widen(const char* low, const char* high,
-                                    charT* dest) const;
-S     virtual char         do_narrow(charT, char dfault) const;
-S     virtual const charT* do_narrow(const charT* low, const charT* high,
-                                     char dfault, char* dest) const;
-    };
-
-   22.2.1.3  ctype specializations              [lib.facet.ctype.special]
-
-T   template <> class ctype
-      : public locale::facet, public ctype_base {
-    public:
-T     typedef char char_type;
-T     explicit ctype(const mask* tab = 0, bool del = false,
-                     size_t refs = 0);
-T     bool is(mask m, char c) const;
-T     const char* is(const char* low, const char* high, mask* vec) const;
-T     const char* scan_is (mask m,
-                           const char* low, const char* high) const;
-T     const char* scan_not(mask m,
-                           const char* low, const char* high) const;
-T     char        toupper(char c) const;
-T     const char* toupper(char* low, const char* high) const;
-T     char        tolower(char c) const;
-T     const char* tolower(char* low, const char* high) const;
-T     char  widen(char c) const;
-T     const char* widen(const char* low, const char* high, char* to) const;
-T     char  narrow(char c, char dfault) const;
-T     const char* narrow(const char* low, const char* high, char dfault,
-                         char* to) const;
-T     static locale::id id;
-T     static const size_t table_size = IMPLEMENTATION_DEFINED;
-
-    protected:
-T     const mask* table() const throw();
-T     static const mask* classic_table() throw();
-T    ~ctype();                    // virtual
-T     virtual char        do_toupper(char c) const;
-T     virtual const char* do_toupper(char* low, const char* high) const;
-T     virtual char        do_tolower(char c) const;
-T     virtual const char* do_tolower(char* low, const char* high) const;
-
-T     virtual char        do_widen(char c) const;
-T     virtual const char* do_widen(const char* low,
-                                   const char* high,
-                                   char* to) const;
-T     virtual char        do_narrow(char c, char dfault) const;
-T     virtual const char* do_narrow(const char* low,
-                                    const char* high,
-                                    char dfault, char* to) const;
-    };
-
-
-   22.2.1.4  Class                      [lib.locale.ctype.byname.special]
-       ctype_byname
-
-X   template <> class ctype_byname : public ctype {
-    public:
-S     explicit ctype_byname(const char*, size_t refs = 0);
-    protected:
-S    ~ctype_byname();             // virtual
-S     virtual char        do_toupper(char c) const;
-S     virtual const char* do_toupper(char* low, const char* high) const;
-S     virtual char        do_tolower(char c) const;
-S     virtual const char* do_tolower(char* low, const char* high) const;
-
-S     virtual char        do_widen(char c) const;
-S     virtual const char* do_widen(char* low,
-                                   const char* high,
-                                   char* to) const;
-S     virtual char        do_widen(char c) const;
-S     virtual const char* do_widen(char* low, const char* high) const;
-
-    };
-
-
-
-   22.2.1.5  Template class codecvt                  [lib.locale.codecvt]
-
-T  class codecvt_base {
-   public:
-T   enum result { ok, partial, error, noconv };
-   };
-
-T  template 
-   class codecvt : public locale::facet, public codecvt_base {
-   public:
-T   typedef internT  intern_type;
-T   typedef externT  extern_type;
-T   typedef stateT state_type;
-T   explicit codecvt(size_t refs = 0)
-T   result out(stateT& state,
-     const internT* from, const internT* from_end, const internT*& from_next,
-           externT*   to,       externT* to_limit, externT*& to_next) const;
-T   result unshift(stateT& state,
-           externT*   to,        externT* to_limit, externT*& to_next) const;
-T   result in(stateT& state,
-     const externT* from, const externT* from_end, const externT*& from_next,
-           internT*   to,       internT* to_limit, internT*& to_next) const;
-T   int encoding() const throw();
-T   bool always_noconv() const throw();
-T   int length(const stateT&, const externT* from, const externT* end,
-               size_t max) const;
-T   int max_length() const throw();
-T   static locale::id id;
-
-   protected:
-T   ~codecvt();                   // virtual
-T   virtual result do_out(stateT& state,
-     const internT* from, const internT* from_end, const internT*& from_next,
-           externT* to,         externT* to_limit, externT*& to_next) const;
-T   virtual result do_in(stateT& state,
-T    const externT* from, const externT* from_end, const externT*& from_next,
-           internT* to,         internT* to_limit, internT*& to_next) const;
-T   virtual result do_unshift(stateT& state,
-           externT* to,         externT* to_limit, externT*& to_next) const;
-T   virtual int do_encoding() const throw();
-T   virtual bool do_always_noconv() const throw();
-T   virtual int do_length(const stateT&, const externT* from,
-                          const externT* end, size_t max) const;
-T   virtual int do_max_length() const throw();
-   };
-   }
-
-
-   22.2.1.6  Template class                   [lib.locale.codecvt.byname]
-       codecvt_byname
-
-X  template 
-   class codecvt_byname : public codecvt {
-   public:
-S   explicit codecvt_byname(const char*, size_t refs = 0);
-   protected:
-S  ~codecvt_byname();             // virtual
-S   virtual result do_out(stateT& state,
-      const internT* from, const internT* from_end, const internT*& from_next,
-            externT* to,         externT* to_limit, externT*& to_next) const;
-S   virtual result do_in(stateT& state,
-      const externT* from, const externT* from_end, const externT*& from_next,
-            internT* to,         internT* to_limit, internT*& to_next) const;
-S   virtual result do_unshift(stateT& state,
-            externT* to,         externT* to_limit, externT*& to_next) const;
-S   virtual int do_encoding() const throw();
-S   virtual bool do_always_noconv() const throw();
-S   virtual int do_length(const stateT&, const externT* from,
-                          const externT* end, size_t max) const;
-S   virtual result do_unshift(stateT& state,
-           externT* to, externT* to_limit, externT*& to_next) const;
-S   virtual int do_max_length() const throw();
-    };
-
-
-   22.2.2.1  Template class num_get                  [lib.locale.num.get]
-
-X   template  >
-    class num_get : public locale::facet {
-    public:
-T     typedef charT            char_type;
-T     typedef InputIterator    iter_type;
-T     explicit num_get(size_t refs = 0);
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, bool& v)           const;
-T     iter_type get(iter_type in, iter_type end, ios_base& ,
-                    ios_base::iostate& err, long& v)           const;
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, unsigned short& v) const;
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, unsigned int& v)   const;
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, unsigned long& v)  const;
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, float& v)          const;
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, double& v)         const;
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, long double& v)    const;
-T     iter_type get(iter_type in, iter_type end, ios_base&,
-                    ios_base::iostate& err, void*& v)          const;
-T     static locale::id id;
-
-    protected:
-T    ~num_get();                  // virtual
-T     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, bool& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, long& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, unsigned short& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, unsigned int& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, unsigned long& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, float& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, double& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, long double& v) const;
-S     virtual iter_type do_get(iter_type, iter_type, ios_base&,
-          ios_base::iostate& err, void*& v) const;
-    };
-
-
-
-   22.2.2.2  Template class num_put                   [lib.locale.nm.put]
-
-X   template  >
-    class num_put : public locale::facet {
-    public:
-T     typedef charT            char_type;
-T     typedef OutputIterator   iter_type;
-T     explicit num_put(size_t refs = 0);
-T     iter_type put(iter_type s, ios_base& f, char_type fill, bool v) const;
-T     iter_type put(iter_type s, ios_base& f, char_type fill, long v) const;
-T     iter_type put(iter_type s, ios_base& f, char_type fill,
-                    unsigned long v) const;
-T     iter_type put(iter_type s, ios_base& f, char_type fill,
-                    double v) const;
-T     iter_type put(iter_type s, ios_base& f, char_type fill,
-                    long double v) const;
-T     iter_type put(iter_type s, ios_base& f, char_type fill,
-                    const void* v) const;
-T     static locale::id id;
-    protected:
-T    ~num_put();                  // virtual
-T     virtual iter_type do_put(iter_type, ios_base&, char_type fill,
-                               bool v) const;
-T     virtual iter_type do_put(iter_type, ios_base&, char_type fill,
-                               long v) const;
-T     virtual iter_type do_put(iter_type, ios_base&, char_type fill,
-                               unsigned long) const;
-S     virtual iter_type do_put(iter_type, ios_base&, char_type fill,
-                               double v) const;
-S     virtual iter_type do_put(iter_type, ios_base&, char_type fill,
-                               long double v) const;
-T     virtual iter_type do_put(iter_type, ios_base&, char_type fill,
-                               const void* v) const;
-    };
-   }
-
-   22.2.3.1  Template class numpunct                [lib.locale.numpunct]
-
-T   template 
-    class numpunct : public locale::facet {
-    public:
-T     typedef charT               char_type;
-T     typedef basic_string string_type;
-T     explicit numpunct(size_t refs = 0);
-T     char_type    decimal_point()   const;
-T     char_type    thousands_sep()   const;
-T     string       grouping()        const;
-T     string_type  truename()        const;
-T     string_type  falsename()       const;
-T     static locale::id id;
-    protected:
-T    ~numpunct();                 // virtual
-T     virtual char_type    do_decimal_point() const;
-T     virtual char_type    do_thousands_sep() const;
-T     virtual string       do_grouping()      const;
-T     virtual string_type  do_truename()      const;      // for bool
-T     virtual string_type  do_falsename()     const;      // for bool
-    };
-   }
-
-
-
-   22.2.3.2  Template class                  [lib.locale.numpunct.byname]
-       numpunct_byname
-
-X   template 
-    class numpunct_byname : public numpunct {
-   // this class is specialized for char and wchar_t.
-    public:
-T     typedef charT                char_type;
-T     typedef basic_string  string_type;
-S     explicit numpunct_byname(const char*, size_t refs = 0);
-    protected:
-S    ~numpunct_byname();          // virtual
-S     virtual char_type    do_decimal_point() const;
-S     virtual char_type    do_thousands_sep() const;
-S     virtual string       do_grouping()      const;
-S     virtual string_type  do_truename()      const;      // for bool
-S     virtual string_type  do_falsename()     const;      // for bool
-    };
-
-
-   22.2.4.1  Template class collate                  [lib.locale.collate]
-
-T   template 
-    class collate : public locale::facet {
-    public:
-T     typedef charT               char_type;
-T     typedef basic_string string_type;
-T     explicit collate(size_t refs = 0);
-T     int compare(const charT* low1, const charT* high1,
-                  const charT* low2, const charT* high2) const;
-T     string_type transform(const charT* low, const charT* high) const;
-T     long hash(const charT* low, const charT* high) const;
-T     static locale::id id;
-    protected:
-T    ~collate();                  // virtual
-T     virtual int    do_compare(const charT* low1, const charT* high1,
-                                const charT* low2, const charT* high2) const;
-T     virtual string_type do_transform
-                               (const charT* low, const charT* high) const;
-T     virtual long   do_hash   (const charT* low, const charT* high) const;
-    };
-
-
-   22.2.4.2  Template class                   [lib.locale.collate.byname]
-       collate_byname
-
-X   template 
-    class collate_byname : public collate {
-    public:
-T     typedef basic_string string_type;
-T     explicit collate_byname(const char*, size_t refs = 0);
-    protected:
-S    ~collate_byname();           // virtual
-S     virtual int    do_compare(const charT* low1, const charT* high1,
-                                const charT* low2, const charT* high2) const;
-S     virtual string_type do_transform
-                               (const charT* low, const charT* high) const;
-S     virtual long   do_hash   (const charT* low, const charT* high) const;
-    };
-
-
-   22.2.5.1  Template class time_get                [lib.locale.time.get]
-
-T   class time_base {
-    public:
-T     enum dateorder { no_order, dmy, mdy, ymd, ydm };
-    };
-
-    [Note: semantics of time_get members are implementation-defined.
-     To complete implementation requires documenting behavior.]
-
-X   template  >
-    class time_get : public locale::facet, public time_base {
-    public:
-T     typedef charT            char_type;
-T     typedef InputIterator    iter_type;
-T     explicit time_get(size_t refs = 0);
-
-T     dateorder date_order()  const { return do_date_order(); }
-T     iter_type get_time(iter_type s, iter_type end, ios_base& f,
-                         ios_base::iostate& err, tm* t)  const;
-T     iter_type get_date(iter_type s, iter_type end, ios_base& f,
-                         ios_base::iostate& err, tm* t)  const;
-T     iter_type get_weekday(iter_type s, iter_type end, ios_base& f,
-                            ios_base::iostate& err, tm* t) const;
-T     iter_type get_monthname(iter_type s, iter_type end, ios_base& f,
-                              ios_base::iostate& err, tm* t) const;
-T     iter_type get_year(iter_type s, iter_type end, ios_base& f,
-                         ios_base::iostate& err, tm* t) const;
-T     static locale::id id;
-    protected:
-     ~time_get();                 // virtual
-X     virtual dateorder do_date_order()  const;
-S     virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&,
-                                    ios_base::iostate& err, tm* t) const;
-S     virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&,
-                                    ios_base::iostate& err, tm* t) const;
-S     virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&,
-                                       ios_base::iostate& err, tm* t) const;
-S     virtual iter_type do_get_monthname(iter_type s, ios_base&,
-                                         ios_base::iostate& err, tm* t) const;
-S     virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&,
-                                    ios_base::iostate& err, tm* t) const;
-    };
-
-
-
-   22.2.5.2  Template class                  [lib.locale.time.get.byname]
-       time_get_byname
-
-X   template  >
-    class time_get_byname : public time_get {
-    public:
-T     typedef time_base::dateorder dateorder;
-T     typedef InputIterator        iter_type
-
-S     explicit time_get_byname(const char*, size_t refs = 0);
-    protected:
-S    ~time_get_byname();          // virtual
-S     virtual dateorder do_date_order()  const;
-S     virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&,
-                                    ios_base::iostate& err, tm* t) const;
-S     virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&,
-                                    ios_base::iostate& err, tm* t) const;
-T     virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&,
-                                       ios_base::iostate& err, tm* t) const;
-T     virtual iter_type do_get_monthname(iter_type s, iter_type end, ios_base&,
-                                         ios_base::iostate& err, tm* t) const;
-S     virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&,
-                                    ios_base::iostate& err, tm* t) const;
-    };
-   }
-
-   22.2.5.3  Template class time_put                [lib.locale.time.put]
-
-X   template  >
-    class time_put : public locale::facet {
-    public:
-T     typedef charT            char_type;
-T     typedef OutputIterator   iter_type;
-T     explicit time_put(size_t refs = 0);
-      // the following is implemented in terms of other member functions.
-S     iter_type put(iter_type s, ios_base& f, char_type fill, const tm* tmb,
-                    const charT* pattern, const charT* pat_end) const;
-T     iter_type put(iter_type s, ios_base& f, char_type fill,
-                    const tm* tmb, char format, char modifier = 0) const;
-T     static locale::id id;
-    protected:
-T    ~time_put();                 // virtual
-S     virtual iter_type do_put(iter_type s, ios_base&, char_type, const tm* t,
-                               char format, char modifier) const;
-    };
-
-
-
-   22.2.5.4  Template class                  [lib.locale.time.put.byname]
-       time_put_byname
-
-T   template  >
-    class time_put_byname : public time_put
-    {
-    public:
-T     typedef charT          char_type;
-T     typedef OutputIterator iter_type;
-
-T     explicit time_put_byname(const char*, size_t refs = 0);
-    protected:
-T    ~time_put_byname();          // virtual
-S     virtual iter_type do_put(iter_type s, ios_base&, char_type, const tm* t,
-                               char format, char modifier) const;
-    };
-
-
-   22.2.6.1  Template class money_get              [lib.locale.money.get]
-
-X   template  >
-    class money_get : public locale::facet {
-    public:
-T     typedef charT               char_type;
-T     typedef InputIterator       iter_type;
-T     typedef basic_string string_type;
-T     explicit money_get(size_t refs = 0);
-T     iter_type get(iter_type s, iter_type end, bool intl,
-                    ios_base& f, ios_base::iostate& err,
-                    long double& units) const;
-T     iter_type get(iter_type s, iter_type end, bool intl,
-                    ios_base& f, ios_base::iostate& err,
-                    string_type& digits) const;
-T     static locale::id id;
-    protected:
-T    ~money_get();                // virtual
-S     virtual iter_type do_get(iter_type, iter_type, bool, ios_base&,
-                       ios_base::iostate& err, long double& units) const;
-S     virtual iter_type do_get(iter_type, iter_type, bool, ios_base&,
-                       ios_base::iostate& err, string_type& digits) const;
-    };
-
-   22.2.6.2  Template class money_put              [lib.locale.money.put]
-
-X   template  >
-    class money_put : public locale::facet {
-    public:
-T     typedef charT               char_type;
-T     typedef OutputIterator      iter_type;
-T     typedef basic_string string_type;
-T     explicit money_put(size_t refs = 0);
-T     iter_type put(iter_type s, bool intl, ios_base& f,
-                    char_type fill, long double units) const;
-T     iter_type put(iter_type s, bool intl, ios_base& f,
-                    char_type fill, const string_type& digits) const;
-T     static locale::id id;
-
-    protected:
-T    ~money_put();                // virtual
-S     virtual iter_type
-        do_put(iter_type, bool, ios_base&, char_type fill,
-               long double units) const;
-S     virtual iter_type
-        do_put(iter_type, bool, ios_base&, char_type fill,
-               const string_type& digits) const;
-    };
-
-
-   22.2.6.3  Template class moneypunct            [lib.locale.moneypunct]
-
-T   class money_base {
-    public:
-T     enum part { none, space, symbol, sign, value };
-T     struct pattern { char field[4]; };
-    };
-
-X   template 
-    class moneypunct : public locale::facet, public money_base {
-    public:
-T     typedef charT char_type;
-T     typedef basic_string string_type;
-T     explicit moneypunct(size_t refs = 0);
-T     charT        decimal_point() const;
-T     charT        thousands_sep() const;
-T     string       grouping()      const;
-T     string_type  curr_symbol()   const;
-T     string_type  positive_sign() const;
-T     string_type  negative_sign() const;
-T     int          frac_digits()   const;
-T     pattern      pos_format()    const;
-T     pattern      neg_format()    const;
-T     static locale::id id;
-T     static const bool intl = International;
-    protected:
-T    ~moneypunct();               // virtual
-S     virtual charT        do_decimal_point() const;
-S     virtual charT        do_thousands_sep() const;
-S     virtual string       do_grouping()      const;
-S     virtual string_type  do_curr_symbol()   const;
-S     virtual string_type  do_positive_sign() const;
-S     virtual string_type  do_negative_sign() const;
-S     virtual int          do_frac_digits()   const;
-T     virtual pattern      do_pos_format()    const;
-T     virtual pattern      do_neg_format()    const;
-    };
-   }
-
-   22.2.6.4  Template class                [lib.locale.moneypunct.byname]
-       moneypunct_byname
-
-X   template 
-    class moneypunct_byname : public moneypunct {
-    public:
-T     typedef money_base::pattern pattern;
-T     typedef basic_string string_type;
-
-T     explicit moneypunct_byname(const char*, size_t refs = 0);
-    protected:
-T    ~moneypunct_byname();        // virtual
-S     virtual charT        do_decimal_point() const;
-S     virtual charT        do_thousands_sep() const;
-S     virtual string       do_grouping()      const;
-S     virtual string_type  do_curr_symbol()   const;
-S     virtual string_type  do_positive_sign() const;
-S     virtual string_type  do_negative_sign() const;
-S     virtual int          do_frac_digits()   const;
-S     virtual pattern      do_pos_format()    const;
-S     virtual pattern      do_neg_format()    const;
-    };
-
-   22.2.7.1  Template class messages                [lib.locale.messages]
-
-T   class messages_base {
-    public:
-T     typedef int catalog;
-    };
-
-X   template 
-    class messages : public locale::facet, public messages_base {
-    public:
-T     typedef charT char_type;
-T     typedef basic_string string_type;
-T     explicit messages(size_t refs = 0);
-T     catalog open(const basic_string& fn, const locale&) const;
-T     string_type  get(catalog c, int set, int msgid,
-                       const string_type& dfault) const;
-T     void    close(catalog c) const;
-T     static locale::id id;
-    protected:
-T    ~messages();                 // virtual
-S     virtual catalog do_open(const basic_string&, const locale&) const;
-S     virtual string_type  do_get(catalog, int set, int msgid,
-                             const string_type& dfault) const;
-S     virtual void    do_close(catalog) const;
-    };
-
-   22.2.7.2  Template class                  [lib.locale.messages.byname]
-       messages_byname
-
-
-X   template 
-    class messages_byname : public messages {
-    public:
-T     typedef messages_base::catalog catalog;
-T     typedef basic_string    string_type;
-
-T     explicit messages_byname(const char*, size_t refs = 0);
-    protected:
-T    ~messages_byname();          // virtual
-S     virtual catalog do_open(const basic_string&, const locale&) const;
-S     virtual string_type  do_get(catalog, int set, int msgid,
-                             const string_type& dfault) const;
-S     virtual void    do_close(catalog) const;
-    };
-
-
-   22.3  C Library Locales                                [lib.c.locales]
-
-
-                   Table 13--Header  synopsis
-            Macros:
-X                        LC_ALL        LC_COLLATE   LC_CTYPE
-X                        LC_MONETARY   LC_NUMERIC   LC_TIME
-X                        NULL
-X           Struct:      lconv
-X           Functions:   localeconv    setlocale
-
-
-   23.2  Sequences                                        [lib.sequences]
-
-   , , , , and .
-
-   Header  synopsis
-
-T   template  > class deque;
-T   template 
-      bool operator==(const deque& x, const deque& y);
-T   template 
-      bool operator< (const deque& x, const deque& y);
-T   template 
-      bool operator!=(const deque& x, const deque& y);
-T   template 
-      bool operator> (const deque& x, const deque& y);
-T   template 
-      bool operator>=(const deque& x, const deque& y);
-T   template 
-      bool operator<=(const deque& x, const deque& y);
-T   template 
-      void swap(deque& x, deque& y);
-   }
-
-   Header  synopsis
-
-T   template  > class list;
-T   template 
-      bool operator==(const list& x, const list& y);
-T   template 
-      bool operator< (const list& x, const list& y);
-T   template 
-      bool operator!=(const list& x, const list& y);
-T   template 
-      bool operator> (const list& x, const list& y);
-T   template 
-      bool operator>=(const list& x, const list& y);
-T   template 
-      bool operator<=(const list& x, const list& y);
-T   template 
-      void swap(list& x, list& y);
-   }
-
-   Header  synopsis
-
-   namespace std {
-T   template  > class queue;
-T   template 
-      bool operator==(const queue& x,
-                      const queue& y);
-T   template 
-      bool operator< (const queue& x,
-                      const queue& y);
-T   template 
-      bool operator!=(const queue& x,
-                      const queue& y);
-T   template 
-      bool operator> (const queue& x,
-                      const queue& y);
-T   template 
-      bool operator>=(const queue& x,
-                      const queue& y);
-T   template 
-      bool operator<=(const queue& x,
-                      const queue& y);
-T   template ,
-              class Compare = less >
-T   class priority_queue;
-   }
-
-   Header  synopsis
-
-   namespace std {
-T   template  > class stack;
-T   template 
-      bool operator==(const stack& x,
-                      const stack& y);
-T   template 
-      bool operator< (const stack& x,
-                      const stack& y);
-T   template 
-      bool operator!=(const stack& x,
-                      const stack& y);
-T   template 
-      bool operator> (const stack& x,
-                      const stack& y);
-T   template 
-      bool operator>=(const stack& x,
-                      const stack& y);
-T   template 
-      bool operator<=(const stack& x,
-                      const stack& y);
-   }
-
-   Header  synopsis
-
-T   template  > class vector;
-
-T   template 
-      bool operator==(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator< (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator!=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator> (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator>=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator<=(const vector& x,
-                      const vector& y);
-T   template 
-      void swap(vector& x, vector& y);
-
-T   template  class vector;
-T   template 
-      bool operator==(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator< (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator!=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator> (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator>=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator<=(const vector& x,
-                      const vector& y);
-T   template 
-      void swap(vector& x, vector& y);
-   }
-
-   23.2.1  Template class deque                               [lib.deque]
-
-    template  >
-T   class deque {
-    public:
-      // types:
-T     typedef typename Allocator::reference         reference;
-T     typedef typename Allocator::const_reference   const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type;
-T     typedef T                                     value_type;
-T     typedef Allocator                             allocator_type;
-T     typedef typename Allocator::pointer           pointer;
-T     typedef typename Allocator::const_pointer     const_pointer;
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-      // _lib.deque.cons_ construct/copy/destroy:
-T     explicit deque(const Allocator& = Allocator());
-T     explicit deque(size_type n, const T& value = T(),
-          const Allocator& = Allocator());
-T     template 
-        deque(InputIterator first, InputIterator last,
-              const Allocator& = Allocator());
-T     deque(const deque& x);
-T    ~deque();
-T     deque& operator=(const deque& x);
-T     template 
-        void assign(InputIterator first, InputIterator last);
-T     void assign(size_type n, const T& t);
-T     allocator_type get_allocator() const;
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // _lib.deque.capacity_ capacity:
-T     size_type size() const;
-T     size_type max_size() const;
-T     void      resize(size_type sz, T c = T());
-T     bool      empty() const;
-
-      // element access:
-T     reference       operator[](size_type n);
-T     const_reference operator[](size_type n) const;
-T     reference       at(size_type n);
-T     const_reference at(size_type n) const;
-T     reference       front();
-T     const_reference front() const;
-T     reference       back();
-T     const_reference back() const;
-      // _lib.deque.modifiers_ modifiers:
-T     void push_front(const T& x);
-T     void push_back(const T& x);
-T     iterator insert(iterator position, const T& x);
-T     void     insert(iterator position, size_type n, const T& x);
-T     template 
-        void insert (iterator position,
-                     InputIterator first, InputIterator last);
-T     void pop_front();
-T     void pop_back();
-T     iterator erase(iterator position);
-T     iterator erase(iterator first, iterator last);
-T     void     swap(deque&);
-T     void     clear();
-    };
-T   template 
-      bool operator==(const deque& x,
-                      const deque& y);
-T   template 
-      bool operator< (const deque& x,
-                      const deque& y);
-T   template 
-      bool operator!=(const deque& x,
-                      const deque& y);
-T   template 
-      bool operator> (const deque& x,
-                      const deque& y);
-T   template 
-      bool operator>=(const deque& x,
-                      const deque& y);
-T   template 
-      bool operator<=(const deque& x,
-                      const deque& y);
-    // specialized algorithms:
-T   template 
-      void swap(deque& x, deque& y);
-
-
-   23.2.2  Template class list                                 [lib.list]
-
-T   template  >
-    class list {
-    public:
-      // types:
-T     typedef typename Allocator::reference         reference;
-T     typedef typename Allocator::const_reference   const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type;
-T     typedef T                                     value_type;
-T     typedef Allocator                             allocator_type;
-T     typedef typename Allocator::pointer           pointer;
-T     typedef typename Allocator::const_pointer     const_pointer;
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-
-      // _lib.list.cons_ construct/copy/destroy:
-T     explicit list(const Allocator& = Allocator());
-T     explicit list(size_type n, const T& value = T(),
-                    const Allocator& = Allocator());
-T     template 
-        list(InputIterator first, InputIterator last,
-             const Allocator& = Allocator());
-T     list(const list& x);
-T    ~list();
-T     list& operator=(const list& x);
-T     template 
-        void assign(InputIterator first, InputIterator last);
-T     void assign(size_type n, const T& t);
-T     allocator_type get_allocator() const;
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // _lib.list.capacity_ capacity:
-T     bool      empty() const;
-T     size_type size() const;
-T     size_type max_size() const;
-T     void      resize(size_type sz, T c = T());
-      // element access:
-T     reference       front();
-T     const_reference front() const;
-T     reference       back();
-T     const_reference back() const;
-      // _lib.list.modifiers_ modifiers:
-T     void push_front(const T& x);
-T     void pop_front();
-T     void push_back(const T& x);
-T     void pop_back();
-T     iterator insert(iterator position, const T& x);
-T     void     insert(iterator position, size_type n, const T& x);
-T     template 
-        void insert(iterator position, InputIterator first,
-                    InputIterator last);
-T     iterator erase(iterator position);
-T     iterator erase(iterator position, iterator last);
-T     void     swap(list&);
-T     void     clear();
-      // _lib.list.ops_ list operations:
-T     void splice(iterator position, list& x);
-T     void splice(iterator position, list& x, iterator i);
-T     void splice(iterator position, list& x, iterator first,
-                  iterator last);
-T     void remove(const T& value);
-T     template  void remove_if(Predicate pred);
-
-T     void unique();
-T     template 
-        void unique(BinaryPredicate binary_pred);
-T     void merge(list& x);
-T     template  void merge(list& x, Compare comp);
-        void sort();
-T     template  void sort(Compare comp);
-        void reverse();
-    };
-T   template 
-      bool operator==(const list& x, const list& y);
-T   template 
-      bool operator< (const list& x, const list& y);
-T   template 
-      bool operator!=(const list& x, const list& y);
-T   template 
-      bool operator> (const list& x, const list& y);
-T   template 
-      bool operator>=(const list& x, const list& y);
-T   template 
-      bool operator<=(const list& x, const list& y);
-    // specialized algorithms:
-T   template 
-      void swap(list& x, list& y);
-
-
-   23.2.3.1  Template class queue                             [lib.queue]
-
-T   template  >
-    class queue {
-    public:
-T     typedef typename Container::value_type            value_type;
-T     typedef typename Container::size_type             size_type;
-T     typedef          Container                        container_type;
-    protected:
-T     Container c;
-    public:
-T     explicit queue(const Container& = Container());
-
-T     bool      empty() const             { return c.empty(); }
-T     size_type size()  const             { return c.size(); }
-T     value_type&       front()           { return c.front(); }
-T     const value_type& front() const     { return c.front(); }
-T     value_type&       back()            { return c.back(); }
-T     const value_type& back() const      { return c.back(); }
-T     void push(const value_type& x)      { c.push_back(x); }
-T     void pop()                          { c.pop_front(); }
-    };
-
-T   template 
-      bool operator==(const queue& x,
-                      const queue& y);
-T   template 
-      bool operator< (const queue& x,
-                      const queue& y);
-T   template 
-      bool operator!=(const queue& x,
-                      const queue& y);
-T   template 
-      bool operator> (const queue& x,
-                      const queue& y);
-T   template 
-      bool operator>=(const queue& x,
-                      const queue& y);
-T   template 
-      bool operator<=(const queue& x,
-                      const queue& y);
-
-   23.2.3.2  Template class priority_queue           [lib.priority.queue]
-
-T   template ,
-              class Compare = less >
-    class priority_queue {
-    public:
-T     typedef typename Container::value_type            value_type;
-T     typedef typename Container::size_type             size_type;
-T     typedef          Container                        container_type;
-    protected:
-T     Container c;
-T     Compare comp;
-    public:
-T     explicit priority_queue(const Compare& x = Compare(),
-                              const Container& = Container());
-T     template 
-        priority_queue(InputIterator first, InputIterator last,
-                       const Compare& x = Compare(),
-                       const Container& = Container());
-
-T     bool      empty() const       { return c.empty(); }
-T     size_type size()  const       { return c.size(); }
-T     const value_type& top() const { return c.front(); }
-T     void push(const value_type& x);
-T     void pop();
-    };
-
-   23.2.3.3  Template class stack                             [lib.stack]
-
-T   template  >
-    class stack {
-    public:
-T     typedef typename Container::value_type            value_type;
-T     typedef typename Container::size_type             size_type;
-T     typedef          Container                        container_type;
-    protected:
-T     Container c;
-    public:
-T     explicit stack(const Container& = Container());
-
-T     bool      empty() const             { return c.empty(); }
-T     size_type size()  const             { return c.size(); }
-T     value_type&       top()             { return c.back(); }
-T     const value_type& top() const       { return c.back(); }
-T     void push(const value_type& x)      { c.push_back(x); }
-T     void pop()                          { c.pop_back(); }
-    };
-T   template 
-      bool operator==(const stack& x,
-                      const stack& y);
-T   template 
-      bool operator< (const stack& x,
-                      const stack& y);
-T   template 
-      bool operator!=(const stack& x,
-                      const stack& y);
-T   template 
-      bool operator> (const stack& x,
-                      const stack& y);
-T   template 
-      bool operator>=(const stack& x,
-                      const stack& y);
-T   template 
-      bool operator<=(const stack& x,
-                      const stack& y);
-
-   23.2.4  Template class vector                             [lib.vector]
-
-    template  >
-T   class vector {
-    public:
-      // types:
-T     typedef typename Allocator::reference         reference;
-T     typedef typename Allocator::const_reference   const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type;
-T     typedef T                                     value_type;
-T     typedef Allocator                             allocator_type;
-T     typedef typename Allocator::pointer           pointer;
-T     typedef typename Allocator::const_pointer     const_pointer
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-      // _lib.vector.cons_ construct/copy/destroy:
-T     explicit vector(const Allocator& = Allocator());
-T     explicit vector(size_type n, const T& value = T(),
-          const Allocator& = Allocator());
-T     template 
-        vector(InputIterator first, InputIterator last,
-          const Allocator& = Allocator());
-T     vector(const vector& x);
-T    ~vector();
-T     vector& operator=(const vector& x);
-T     template 
-        void assign(InputIterator first, InputIterator last);
-T     void assign(size_type n, const T& u);
-T     allocator_type get_allocator() const;
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // _lib.vector.capacity_ capacity:
-T     size_type size() const;
-T     size_type max_size() const;
-T     void      resize(size_type sz, T c = T());
-T     size_type capacity() const;
-T     bool      empty() const;
-T     void      reserve(size_type n);
-
-      // element access:
-T     reference       operator[](size_type n);
-T     const_reference operator[](size_type n) const;
-T     const_reference at(size_type n) const;
-T     reference       at(size_type n);
-T     reference       front();
-T     const_reference front() const;
-T     reference       back();
-T     const_reference back() const;
-      // _lib.vector.modifiers_ modifiers:
-T     void push_back(const T& x);
-T     void pop_back();
-T     iterator insert(iterator position, const T& x);
-T     void     insert(iterator position, size_type n, const T& x);
-T     template 
-          void insert(iterator position,
-                      InputIterator first, InputIterator last);
-T     iterator erase(iterator position);
-T     iterator erase(iterator first, iterator last);
-T     void     swap(vector&);
-T     void     clear();
-    };
-
-T   template 
-      bool operator==(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator< (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator!=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator> (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator>=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator<=(const vector& x,
-                      const vector& y);
-    // specialized algorithms:
-T   template 
-      void swap(vector& x, vector& y);
-
-
-   23.2.5  Class vector                           [lib.vector.bool]
-
-T   template  class vector {
-    public:
-      // types:
-T     typedef bool                                  const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type;
-T     typedef bool                                  value_type;
-T     typedef Allocator                             allocator_type;
-T     typedef implementation defined                pointer;
-T     typedef implementation defined                const_pointer
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-      // bit reference:
-T     class reference {
-       friend class vector;
-T      reference();
-      public:
-T      ~reference();
-T       operator bool() const;
-T       reference& operator=(const bool x);
-T       reference& operator=(const reference& x);
-T       void flip();              // flips the bit
-      };
-
-      // construct/copy/destroy:
-T     explicit vector(const Allocator& = Allocator());
-T     explicit vector(size_type n, const bool& value = bool(),
-                      const Allocator& = Allocator());
-T     template 
-        vector(InputIterator first, InputIterator last,
-          const Allocator& = Allocator());
-T     vector(const vector& x);
-T    ~vector();
-T     vector& operator=(const vector& x);
-T     template 
-        void assign(InputIterator first, InputIterator last);
-T     void assign(size_type n, const T& t);
-T     allocator_type get_allocator() const;
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // capacity:
-T     size_type size() const;
-T     size_type max_size() const;
-T     void      resize(size_type sz, bool c = false);
-T     size_type capacity() const;
-T     bool      empty() const;
-T     void      reserve(size_type n);
-      // element access:
-T     reference       operator[](size_type n);
-T     const_reference operator[](size_type n) const;
-T     const_reference at(size_type n) const;
-T     reference       at(size_type n);
-T     reference       front();
-T     const_reference front() const;
-T     reference       back();
-T     const_reference back() const;
-      // modifiers:
-T     void push_back(const bool& x);
-T     void pop_back();
-T     iterator insert(iterator position, const bool& x);
-T     void     insert (iterator position, size_type n, const bool& x);
-T     template 
-          void insert(iterator position,
-                      InputIterator first, InputIterator last);
-T     iterator erase(iterator position);
-T     iterator erase(iterator first, iterator last);
-T     void swap(vector&);
-T     static void swap(reference x, reference y);
-T     void flip();                // flips all bits
-T     void clear();
-    };
-
-T   template 
-      bool operator==(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator< (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator!=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator> (const vector& x,
-                      const vector& y);
-T   template 
-      bool operator>=(const vector& x,
-                      const vector& y);
-T   template 
-      bool operator<=(const vector& x,
-                      const vector& y);
-    // specialized algorithms:
-T   template 
-      void swap(vector& x, vector& y);
-
-   23.3  Associative containers                         [lib.associative]
-
-  and :
-
-   Header  synopsis
-
-    template ,
-              class Allocator = allocator > >
-T     class map;
-
-T   template 
-      bool operator==(const map& x,
-                      const map& y);
-T   template 
-      bool operator< (const map& x,
-                      const map& y);
-T   template 
-      bool operator!=(const map& x,
-                      const map& y);
-T   template 
-      bool operator> (const map& x,
-                      const map& y);
-T   template 
-      bool operator>=(const map& x,
-                      const map& y);
-T   template 
-      bool operator<=(const map& x,
-                      const map& y);
-T   template 
-      void swap(map& x,
-                map& y);
-T   template ,
-              class Allocator = allocator > >
-      class multimap;
-T   template 
-      bool operator==(const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator< (const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator!=(const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator> (const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator>=(const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator<=(const multimap& x,
-                      const multimap& y);
-T   template 
-      void swap(multimap& x,
-                multimap& y);
-   }
-
-   Header  synopsis
-
-    template ,
-              class Allocator = allocator >
-T     class set;
-
-T   template 
-      bool operator==(const set& x,
-                      const set& y);
-T   template 
-      bool operator< (const set& x,
-                      const set& y);
-T   template 
-      bool operator!=(const set& x,
-                      const set& y);
-T   template 
-      bool operator> (const set& x,
-                      const set& y);
-T   template 
-      bool operator>=(const set& x,
-                      const set& y);
-T   template 
-      bool operator<=(const set& x,
-                      const set& y);
-T   template 
-      void swap(set& x,
-                set& y);
-T   template ,
-              class Allocator = allocator >
-      class multiset;
-T   template 
-      bool operator==(const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator< (const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator!=(const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator> (const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator>=(const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator<=(const multiset& x,
-                      const multiset& y);
-T   template 
-      void swap(multiset& x,
-                multiset& y);
-   }
-
-   23.3.1  Template class map                                   [lib.map]
-
-    template ,
-              class Allocator = allocator > >
-T     class map {
-    public:
-      // types:
-T     typedef Key                                   key_type;
-T     typedef T                                     mapped_type;
-T     typedef pair                    value_type;
-T     typedef Compare                               key_compare;
-T     typedef Allocator                             allocator_type;
-T     typedef typename Allocator::reference         reference;
-T     typedef typename Allocator::const_reference   const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type;
-T     typedef typename Allocator::pointer           pointer;
-T     typedef typename Allocator::const_pointer     const_pointer;
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-T     class value_compare
-        : public binary_function {
-      friend class map;
-      protected:
-T       Compare comp;
-T       value_compare(Compare c) : comp(c) {}
-      public:
-T       bool operator()(const value_type& x, const value_type& y) const {
-          return comp(x.first, y.first);
-        }
-      };
-
-      // _lib.map.cons_ construct/copy/destroy:
-T     explicit map(const Compare& comp = Compare(),
-                   const Allocator& = Allocator());
-T     template 
-        map(InputIterator first, InputIterator last,
-            const Compare& comp = Compare(), const Allocator& = Allocator());
-T     map(const map& x);
-T    ~map();
-T     map&
-        operator=(const map& x);
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // capacity:
-T     bool      empty() const;
-T     size_type size() const;
-T     size_type max_size() const;
-      // _lib.map.access_ element access:
-T     T& operator[](const key_type& x);
-      // modifiers:
-T     pair insert(const value_type& x);
-T     iterator             insert(iterator position, const value_type& x);
-T     template 
-        void insert(InputIterator first, InputIterator last);
-T     void      erase(iterator position);
-T     size_type erase(const key_type& x);
-T     void      erase(iterator first, iterator last);
-T     void swap(map&);
-T     void clear();
-      // observers:
-T     key_compare   key_comp() const;
-T     value_compare value_comp() const;
-      // _lib.map.ops_ map operations:
-T     iterator       find(const key_type& x);
-T     const_iterator find(const key_type& x) const;
-T     size_type      count(const key_type& x) const;
-T     iterator       lower_bound(const key_type& x);
-T     const_iterator lower_bound(const key_type& x) const;
-T     iterator       upper_bound(const key_type& x);
-T     const_iterator upper_bound(const key_type& x) const;
-T     pair
-          equal_range(const key_type& x);
-T     pair
-          equal_range(const key_type& x) const;
-    };
-
-T   template 
-      bool operator==(const map& x,
-                      const map& y);
-T   template 
-      bool operator< (const map& x,
-                      const map& y);
-T   template 
-      bool operator!=(const map& x,
-                      const map& y);
-T   template 
-      bool operator> (const map& x,
-                      const map& y);
-T   template 
-      bool operator>=(const map& x,
-                      const map& y);
-T   template 
-      bool operator<=(const map& x,
-                      const map& y);
-    // specialized algorithms:
-T   template 
-      void swap(map& x,
-                map& y);
-
-   23.3.2  Template class multimap                         [lib.multimap]
-
-    template ,
-              class Allocator = allocator > >
-T   class multimap {
-    public:
-      // types:
-T     typedef Key                                   key_type;
-T     typedef T                                     mapped_type;
-T     typedef pair                     value_type;
-T     typedef Compare                               key_compare;
-T     typedef Allocator                             allocator_type;
-T     typedef typename Allocator::reference         reference;
-T     typedef typename Allocator::const_reference   const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type
-T     typedef typename Allocator::pointer           pointer;
-T     typedef typename Allocator::const_pointer     const_pointer;
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-T     class value_compare
-        : public binary_function {
-      friend class multimap;
-      protected:
-T       Compare comp;
-T       value_compare(Compare c) : comp(c) {}
-      public:
-T       bool operator()(const value_type& x, const value_type& y) const {
-          return comp(x.first, y.first);
-        }
-      };
-      // construct/copy/destroy:
-T     explicit multimap(const Compare& comp = Compare(),
-                        const Allocator& = Allocator());
-T     template 
-        multimap(InputIterator first, InputIterator last,
-                 const Compare& comp = Compare(),
-                 const Allocator& = Allocator());
-T     multimap(const multimap& x);
-T    ~multimap();
-T     multimap&
-        operator=(const multimap& x);
-T     allocator_type get_allocator() const;
-
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // capacity:
-T     bool           empty() const;
-T     size_type      size() const;
-T     size_type      max_size() const;
-      // modifiers:
-T     iterator insert(const value_type& x);
-T     iterator insert(iterator position, const value_type& x);
-T     template 
-        void insert(InputIterator first, InputIterator last);
-T     void      erase(iterator position);
-T     size_type erase(const key_type& x);
-T     void      erase(iterator first, iterator last);
-T     void swap(multimap&);
-T     void clear();
-      // observers:
-T     key_compare    key_comp() const;
-T     value_compare  value_comp() const;
-      // map operations:
-T     iterator       find(const key_type& x);
-T     const_iterator find(const key_type& x) const;
-T     size_type      count(const key_type& x) const;
-T     iterator       lower_bound(const key_type& x);
-T     const_iterator lower_bound(const key_type& x) const;
-T     iterator       upper_bound(const key_type& x);
-T     const_iterator upper_bound(const key_type& x) const;
-T     pair             equal_range(const key_type& x);
-T     pair equal_range(const key_type& x) const;
-    };
-
-T   template 
-      bool operator==(const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator< (const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator!=(const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator> (const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator>=(const multimap& x,
-                      const multimap& y);
-T   template 
-      bool operator<=(const multimap& x,
-                      const multimap& y);
-    // specialized algorithms:
-T   template 
-      void swap(multimap& x,
-                multimap& y);
-
-
-   23.3.3  Template class set                                   [lib.set]
-
-    template ,
-              class Allocator = allocator >
-T   class set {
-    public:
-      // types:
-T     typedef Key                                   key_type;
-T     typedef Key                                   value_type;
-T     typedef Compare                               key_compare;
-T     typedef Compare                               value_compare;
-T     typedef Allocator                             allocator_type;
-T     typedef typename Allocator::reference         reference;
-T     typedef typename Allocator::const_reference   const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type;
-T     typedef typename Allocator::pointer           pointer;
-T     typedef typename Allocator::const_pointer     const_pointer;
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-      // _lib.set.cons_ construct/copy/destroy:
-T     explicit set(const Compare& comp = Compare(),
-                   const Allocator& = Allocator());
-T     template 
-        set(InputIterator first, InputIterator last,
-            const Compare& comp = Compare(), const Allocator& = Allocator());
-T     set(const set& x);
-T    ~set();
-T     set&
-        operator=(const set& x);
-T     allocator_type get_allocator() const;
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // capacity:
-T     bool          empty() const;
-T     size_type     size() const;
-T     size_type     max_size() const;
-      // modifiers:
-T     pair insert(const value_type& x);
-T     iterator            insert(iterator position, const value_type& x);
-T     template 
-T         void insert(InputIterator first, InputIterator last);
-T     void      erase(iterator position);
-T     size_type erase(const key_type& x);
-T     void      erase(iterator first, iterator last);
-T     void swap(set&);
-T     void clear();
-
-      // observers:
-T     key_compare   key_comp() const;
-T     value_compare value_comp() const;
-      // set operations:
-T     iterator  find(const key_type& x) const;
-T     size_type count(const key_type& x) const;
-T     iterator  lower_bound(const key_type& x) const;
-T     iterator  upper_bound(const key_type& x) const;
-T     pair equal_range(const key_type& x) const;
-    };
-T   template 
-      bool operator==(const set& x,
-                      const set& y);
-T   template 
-      bool operator< (const set& x,
-                      const set& y);
-T   template 
-      bool operator!=(const set& x,
-                      const set& y);
-T   template 
-      bool operator> (const set& x,
-                      const set& y);
-T   template 
-      bool operator>=(const set& x,
-                      const set& y);
-T   template 
-      bool operator<=(const set& x,
-                      const set& y);
-    // specialized algorithms:
-T   template 
-      void swap(set& x,
-                set& y);
-
-   23.3.4  Template class multiset                         [lib.multiset]
-
-    template ,
-              class Allocator = allocator >
-T   class multiset {
-    public:
-      // types:
-T     typedef Key                                   key_type;
-T     typedef Key                                   value_type;
-T     typedef Compare                               key_compare;
-T     typedef Compare                               value_compare;
-T     typedef Allocator                             allocator_type;
-T     typedef typename Allocator::reference         reference;
-T     typedef typename Allocator::const_reference   const_reference;
-T     typedef implementation defined                iterator;
-T     typedef implementation defined                const_iterator;
-T     typedef implementation defined                size_type;
-T     typedef implementation defined                difference_type
-T     typedef typename Allocator::pointer           pointer;
-T     typedef typename Allocator::const_pointer     const_pointer;
-T     typedef std::reverse_iterator       reverse_iterator;
-T     typedef std::reverse_iterator const_reverse_iterator;
-
-      // construct/copy/destroy:
-T     explicit multiset(const Compare& comp = Compare(),
-                        const Allocator& = Allocator());
-T     template 
-        multiset(InputIterator first, InputIterator last,
-                 const Compare& comp = Compare(),
-                 const Allocator& = Allocator());
-T     multiset(const multiset& x);
-T    ~multiset();
-T     multiset&
-          operator=(const multiset& x);
-T     allocator_type get_allocator() const;
-      // iterators:
-T     iterator               begin();
-T     const_iterator         begin() const;
-T     iterator               end();
-T     const_iterator         end() const;
-T     reverse_iterator       rbegin();
-T     const_reverse_iterator rbegin() const;
-T     reverse_iterator       rend();
-T     const_reverse_iterator rend() const;
-      // capacity:
-T     bool          empty() const;
-T     size_type     size() const;
-T     size_type     max_size() const;
-      // modifiers:
-T     iterator insert(const value_type& x);
-T     iterator insert(iterator position, const value_type& x);
-T     template 
-        void insert(InputIterator first, InputIterator last);
-T     void      erase(iterator position);
-T     size_type erase(const key_type& x);
-T     void      erase(iterator first, iterator last);
-T     void swap(multiset&);
-T     void clear();
-      // observers:
-T     key_compare   key_comp() const;
-T     value_compare value_comp() const;
-      // set operations:
-T     iterator  find(const key_type& x) const;
-T     size_type count(const key_type& x) const;
-T     iterator  lower_bound(const key_type& x) const;
-T     iterator  upper_bound(const key_type& x) const;
-T     pair equal_range(const key_type& x) const;
-    };
-
-T   template 
-      bool operator==(const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator< (const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator!=(const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator> (const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator>=(const multiset& x,
-                      const multiset& y);
-T   template 
-      bool operator<=(const multiset& x,
-                      const multiset& y);
-    // specialized algorithms:
-T   template 
-      void swap(multiset& x,
-                multiset& y);
-
-   23.3.5  Template class bitset                    [lib.template.bitset]
-
-   Header  synopsis
-
-T   template  class bitset;
-    // _lib.bitset.operators_ bitset operations:
-T   template 
-      bitset operator&(const bitset&, const bitset&);
-T   template 
-      bitset operator|(const bitset&, const bitset&);
-T   template 
-      bitset operator^(const bitset&, const bitset&);
-T   template 
-      basic_istream&
-      operator>>(basic_istream& is, bitset& x);
-T   template 
-      basic_ostream&
-      operator<<(basic_ostream& os, const bitset& x);
-
-T   template class bitset {
-    public:
-      // bit reference:
-T     class reference {
-        friend class bitset;
-T       reference();
-      public:
-T      ~reference();
-T       reference& operator=(bool x);             // for b[i] = x;
-T       reference& operator=(const reference&);   // for b[i] = b[j];
-T       bool operator~() const;                   // flips the bit
-T       operator bool() const;                    // for x = b[i];
-T       reference& flip();                        // for b[i].flip();
-      };
-
-      // _lib.bitset.cons_ constructors:
-T     bitset();
-T     bitset(unsigned long val);
-T     template
-        explicit bitset(
-          const basic_string& str,
-          typename basic_string::size_type pos = 0,
-          typename basic_string::size_type n =
-            basic_string::npos);
-      // _lib.bitset.members_ bitset operations:
-T     bitset& operator&=(const bitset& rhs);
-T     bitset& operator|=(const bitset& rhs);
-T     bitset& operator^=(const bitset& rhs);
-T     bitset& operator<<=(size_t pos);
-T     bitset& operator>>=(size_t pos);
-T     bitset& set();
-T     bitset& set(size_t pos, int val = true);
-T     bitset& reset();
-T     bitset& reset(size_t pos);
-T     bitset  operator~() const;
-T     bitset& flip();
-T     bitset& flip(size_t pos);
-      // element access:
-T     reference operator[](size_t pos);         // for b[i];
-T     unsigned long  to_ulong() const;
-T     template 
-        basic_string to_string() const;
-T     size_t count() const;
-T     size_t size()  const;
-T     bool operator==(const bitset& rhs) const;
-T     bool operator!=(const bitset& rhs) const;
-T     bool test(size_t pos) const;
-T     bool any() const;
-T     bool none() const;
-T     bitset operator<<(size_t pos) const;
-T     bitset operator>>(size_t pos) const;
-    };
-
-
-
-
-   24.2  Header  synopsis               [lib.iterator.synopsis]
-
-    // _lib.iterator.primitives_, primitives:
-T   template struct iterator_traits;
-T   template struct iterator_traits;
-
-X   template struct iterator;
-T   struct input_iterator_tag {};
-T   struct output_iterator_tag {};
-T   struct forward_iterator_tag: public input_iterator_tag {};
-T   struct bidirectional_iterator_tag: public forward_iterator_tag {};
-T   struct random_access_iterator_tag: public bidirectional_iterator_tag {};
-    // _lib.iterator.operations_, iterator operations:
-T   template 
-      void advance(InputIterator& i, Distance n);
-T   template 
-      typename iterator_traits::difference_type
-      distance(InputIterator first, InputIterator last);
-    // _lib.predef.iterators_, predefined iterators:
-X   template  class reverse_iterator;
-T   template 
-      bool operator==(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator<(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator!=(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator>(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator>=(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator<=(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      typename reverse_iterator::difference_type operator-(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      reverse_iterator
-        operator+(
-          typename reverse_iterator::difference_type n,
-          const reverse_iterator& x);
-
-X   template  class back_insert_iterator;
-T   template 
-      back_insert_iterator back_inserter(Container& x);
-X   template  class front_insert_iterator;
-T   template 
-      front_insert_iterator front_inserter(Container& x);
-X   template  class insert_iterator;
-T   template 
-      insert_iterator inserter(Container& x, Iterator i);
-    // _lib.stream.iterators_, stream iterators:
-X   template ,
-              class Distance = ptrdiff_t>
-      class istream_iterator;
-    template 
-X     bool operator==(const istream_iterator& x,
-                      const istream_iterator& y);
-    template 
-X     bool operator!=(const istream_iterator& x,
-                      const istream_iterator& y);
-X   template  >
-        class ostream_iterator;
-X   template >
-      class istreambuf_iterator;
-X   template 
-      bool operator==(const istreambuf_iterator& a,
-                      const istreambuf_iterator& b);
-X   template 
-      bool operator!=(const istreambuf_iterator& a,
-                      const istreambuf_iterator& b);
-T   template  >
-      class ostreambuf_iterator;
-
-   24.3  Iterator primitives                    [lib.iterator.primitives]
-
-T   template struct iterator_traits {
-T     typedef typename Iterator::difference_type difference_type;
-T     typedef typename Iterator::value_type value_type;
-T     typedef typename Iterator::pointer pointer;
-T     typedef typename Iterator::reference reference;
-T     typedef typename Iterator::iterator_category iterator_category;
-    };
-
-T   template struct iterator_traits {
-T     typedef ptrdiff_t difference_type;
-T     typedef T value_type;
-T     typedef T* pointer;
-T     typedef T& reference;
-T     typedef random_access_iterator_tag iterator_category;
-    };
-
-T   template struct iterator_traits {
-T     typedef ptrdiff_t difference_type;
-T     typedef T value_type;
-T     typedef const T* pointer;
-T     typedef const T& reference;
-T     typedef random_access_iterator_tag iterator_category;
-    };
-
-   24.3.2  Basic iterator                            [lib.iterator.basic]
-
-    template
-X     struct iterator {
-T         typedef T         value_type;
-T         typedef Distance  difference_type;
-T         typedef Pointer   pointer;
-T         typedef Reference reference;
-T         typedef Category  iterator_category;
-    };
-
-   24.3.3  Standard iterator tags                 [lib.std.iterator.tags]
-
-T   struct input_iterator_tag {};
-T   struct output_iterator_tag {};
-T   struct forward_iterator_tag: public input_iterator_tag {};
-T   struct bidirectional_iterator_tag: public forward_iterator_tag {};
-T   struct random_access_iterator_tag: public bidirectional_iterator_tag {};
-
-
-   24.4.1  Reverse iterators                      [lib.reverse.iterators]
-
-    template 
-X   class reverse_iterator : public
-          iterator::iterator_category,
-                   typename iterator_traits::value_type,
-                   typename iterator_traits::difference_type,
-                   typename iterator_traits::pointer,
-                   typename iterator_traits::reference> {
-    protected:
-T     Iterator current;
-    public:
-T     typedef Iterator
-          iterator_type;
-T     typedef typename iterator_traits::difference_type
-          difference_type;
-T     typedef typename iterator_traits::reference
-          reference;
-T     typedef typename iterator_traits::pointer
-          pointer;
-
-T     reverse_iterator();
-T     explicit reverse_iterator(Iterator x);
-T     template  reverse_iterator(const reverse_iterator& u);
-T     Iterator base() const;      // explicit
-T     reference operator*() const;
-T     pointer   operator->() const;
-T     reverse_iterator& operator++();
-T     reverse_iterator  operator++(int);
-T     reverse_iterator& operator--();
-T     reverse_iterator  operator--(int);
-
-T     reverse_iterator  operator+ (difference_type n) const;
-T     reverse_iterator& operator+=(difference_type n);
-T     reverse_iterator  operator- (difference_type n) const;
-T     reverse_iterator& operator-=(difference_type n);
-T     reference operator[](difference_type n) const;
-    };
-T   template 
-      bool operator==(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator<(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator!=(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator>(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator>=(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      bool operator<=(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      typename reverse_iterator::difference_type operator-(
-        const reverse_iterator& x,
-        const reverse_iterator& y);
-T   template 
-      reverse_iterator operator+(
-        typename reverse_iterator::difference_type n,
-        const reverse_iterator& x);
-
-
-   24.4.2.1  Template class                    [lib.back.insert.iterator]
-       back_insert_iterator
-
-    template 
-X   class back_insert_iterator :
-          public iterator {
-    protected:
-T     Container* container;
-    public:
-T     typedef Container container_type;
-T     explicit back_insert_iterator(Container& x);
-T     back_insert_iterator&
-        operator=(typename Container::const_reference value);
-
-T     back_insert_iterator& operator*();
-T     back_insert_iterator& operator++();
-T     back_insert_iterator  operator++(int);
-    };
-T   template 
-      back_insert_iterator back_inserter(Container& x);
-
-
-
-   24.4.2.3  Template class                   [lib.front.insert.iterator]
-       front_insert_iterator
-
-    template 
-X   class front_insert_iterator :
-          public iterator {
-    protected:
-T     Container* container;
-    public:
-T     typedef Container container_type;
-T     explicit front_insert_iterator(Container& x);
-T     front_insert_iterator&
-        operator=(typename Container::const_reference value);
-T     front_insert_iterator& operator*();
-T     front_insert_iterator& operator++();
-T     front_insert_iterator  operator++(int);
-    };
-T   template 
-      front_insert_iterator front_inserter(Container& x);
-
-
-   24.4.2.5  Template class insert_iterator         [lib.insert.iterator]
-
-    template 
-X   class insert_iterator :
-          public iterator {
-    protected:
-T     Container* container;
-T     typename Container::iterator iter;
-    public:
-T     typedef Container container_type;
-T     insert_iterator(Container& x, typename Container::iterator i);
-T     insert_iterator&
-        operator=(typename Container::const_reference value);
-T     insert_iterator& operator*();
-T     insert_iterator& operator++();
-T     insert_iterator& operator++(int);
-    };
-T   template 
-      insert_iterator inserter(Container& x, Iterator i);
-
-   24.5.1  Template class istream_iterator         [lib.istream.iterator]
-
-    template ,
-        class Distance = ptrdiff_t>
-X   class istream_iterator:
-      public iterator {
-    public:
-T     typedef charT char_type
-T     typedef traits traits_type;
-T     typedef basic_istream istream_type;
-T     istream_iterator();
-T     istream_iterator(istream_type& s);
-T     istream_iterator(const istream_iterator& x);
-T    ~istream_iterator();
-
-T     const T& operator*() const;
-T     const T* operator->() const;
-T     istream_iterator& operator++();
-T     istream_iterator  operator++(int);
-    };
-
-T   template 
-      bool operator==(const istream_iterator& x,
-                      const istream_iterator& y);
-T   template 
-      bool operator!=(const istream_iterator& x,
-                      const istream_iterator& y);
-
-
-   24.5.2  Template class ostream_iterator         [lib.ostream.iterator]
-
-    template  >
-X   class ostream_iterator:
-      public iterator {
-    public:
-T     typedef charT char_type;
-T     typedef traits traits_type;
-T     typedef basic_ostream ostream_type;
-T     ostream_iterator(ostream_type& s);
-T     ostream_iterator(ostream_type& s, const charT* delimiter);
-T     ostream_iterator(const ostream_iterator& x);
-T    ~ostream_iterator();
-T     ostream_iterator& operator=(const T& value);
-
-T     ostream_iterator& operator*();
-T     ostream_iterator& operator++();
-T     ostream_iterator& operator++(int);
-    };
-
-
-   24.5.3  Template class                       [lib.istreambuf.iterator]
-       istreambuf_iterator
-
-    template >
-X   class istreambuf_iterator
-       : public iterator {
-    public:
-T     typedef charT                         char_type;
-T     typedef traits                        traits_type;
-T     typedef typename traits::int_type     int_type;
-T     typedef basic_streambuf streambuf_type;
-T     typedef basic_istream   istream_type;
-T     class proxy;                        // exposition only
-T     istreambuf_iterator() throw();
-T     istreambuf_iterator(istream_type& s) throw();
-T     istreambuf_iterator(streambuf_type* s) throw();
-T     istreambuf_iterator(const proxy& p) throw();
-T     charT operator*() const;
-T     istreambuf_iterator& operator++();
-T     proxy operator++(int);
-X     bool equal(istreambuf_iterator& b);
-    };
-
-T   template 
-      bool operator==(const istreambuf_iterator& a,
-                      const istreambuf_iterator& b);
-
-T   template 
-      bool operator!=(const istreambuf_iterator& a,
-                      const istreambuf_iterator& b);
-
-   24.5.3.1  Template class              [lib.istreambuf.iterator::proxy]
-       istreambuf_iterator::proxy
-
-    template  >
-T     class istreambuf_iterator::proxy
-    {
-T     charT keep_;
-T     basic_streambuf* sbuf_;
-T     proxy(charT c,
-            basic_streambuf* sbuf);
-        : keep_(c), sbuf_(sbuf) {}
-    public:
-T     charT operator*() { return keep_; }
-    };
-
-
-
-   24.5.4  Template class                       [lib.ostreambuf.iterator]
-       ostreambuf_iterator
-
-    template  >
-T   class ostreambuf_iterator:
-      public iterator {
-    public:
-T     typedef charT                         char_type;
-T     typedef traits                        traits_type;
-T     typedef basic_streambuf streambuf_type;
-T     typedef basic_ostream   ostream_type;
-    public:
-T     ostreambuf_iterator(ostream_type& s) throw();
-T     ostreambuf_iterator(streambuf_type* s) throw();
-T     ostreambuf_iterator& operator=(charT c);
-T     ostreambuf_iterator& operator*();
-T     ostreambuf_iterator& operator++();
-T     ostreambuf_iterator& operator++(int);
-T     bool failed() const throw();
-    };
-
-
-   Header  synopsis
-
-
-    // _lib.alg.nonmodifying_, non-modifying sequence operations:
-T   template
-      Function for_each(InputIterator first, InputIterator last, Function f);
-T   template
-      InputIterator find(InputIterator first, InputIterator last,
-                         const T& value);
-T   template
-      InputIterator find_if(InputIterator first, InputIterator last,
-                            Predicate pred);
-T   template
-      ForwardIterator1
-        find_end(ForwardIterator1 first1, ForwardIterator1 last1,
-                 ForwardIterator2 first2, ForwardIterator2 last2);
-T   template
-      ForwardIterator1
-        find_end(ForwardIterator1 first1, ForwardIterator1 last1,
-                 ForwardIterator2 first2, ForwardIterator2 last2,
-                 BinaryPredicate pred);
-T   template
-      ForwardIterator1
-        find_first_of(ForwardIterator1 first1, ForwardIterator1 last1,
-                      ForwardIterator2 first2, ForwardIterator2 last2);
-T   template
-      ForwardIterator1
-        find_first_of(ForwardIterator1 first1, ForwardIterator1 last1,
-                 ForwardIterator2 first2, ForwardIterator2 last2,
-                 BinaryPredicate pred);
-T   template
-      ForwardIterator adjacent_find(ForwardIterator first,
-                                    ForwardIterator last);
-T   template
-      ForwardIterator adjacent_find(ForwardIterator first,
-          ForwardIterator last, BinaryPredicate pred);
-T   template
-      typename iterator_traits::difference_type
-        count(InputIterator first, InputIterator last, const T& value);
-T   template
-      typename iterator_traits::difference_type
-        count_if(InputIterator first, InputIterator last, Predicate pred);
-T   template
-      pair
-        mismatch(InputIterator1 first1, InputIterator1 last1,
-                 InputIterator2 first2);
-T   template
-      pair
-        mismatch(InputIterator1 first1, InputIterator1 last1,
-                 InputIterator2 first2, BinaryPredicate pred);
-
-T   template
-      bool equal(InputIterator1 first1, InputIterator1 last1,
-                 InputIterator2 first2);
-T   template
-      bool equal(InputIterator1 first1, InputIterator1 last1,
-                 InputIterator2 first2, BinaryPredicate pred);
-T   template
-      ForwardIterator1 search(ForwardIterator1 first1, ForwardIterator1 last1,
-                              ForwardIterator2 first2, ForwardIterator2 last2);
-T   template
-      ForwardIterator1 search(ForwardIterator1 first1, ForwardIterator1 last1,
-                              ForwardIterator2 first2, ForwardIterator2 last2,
-                              BinaryPredicate pred);
-T   template
-      ForwardIterator  search_n(ForwardIterator first, ForwardIterator last,
-                              Size count, const T& value);
-T   template
-      ForwardIterator1 search_n(ForwardIterator first, ForwardIterator last,
-                              Size count, const T& value,
-                              BinaryPredicate pred);
-    // _lib.alg.modifying.operations_, modifying sequence operations:
-    // _lib.alg.copy_, copy:
-T   template
-      OutputIterator copy(InputIterator first, InputIterator last,
-                          OutputIterator result);
-T   template
-      BidirectionalIterator2
-        copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last,
-                      BidirectionalIterator2 result);
-    // _lib.alg.swap_, swap:
-T   template void swap(T& a, T& b);
-T   template
-      ForwardIterator2 swap_ranges(ForwardIterator1 first1,
-          ForwardIterator1 last1, ForwardIterator2 first2);
-T   template
-      void iter_swap(ForwardIterator1 a, ForwardIterator2 b);
-T   template
-      OutputIterator transform(InputIterator first, InputIterator last,
-                               OutputIterator result, UnaryOperation op);
-T   template
-      OutputIterator transform(InputIterator1 first1, InputIterator1 last1,
-                               InputIterator2 first2, OutputIterator result,
-                               BinaryOperation binary_op);
-
-T   template
-      void replace(ForwardIterator first, ForwardIterator last,
-                   const T& old_value, const T& new_value);
-T   template
-      void replace_if(ForwardIterator first, ForwardIterator last,
-                      Predicate pred, const T& new_value);
-T   template
-      OutputIterator replace_copy(InputIterator first, InputIterator last,
-                                  OutputIterator result,
-                                  const T& old_value, const T& new_value);
-T   template
-      OutputIterator replace_copy_if(Iterator first, Iterator last,
-                                     OutputIterator result,
-                                     Predicate pred, const T& new_value);
-T   template
-      void fill(ForwardIterator first, ForwardIterator last, const T& value);
-T   template
-      void fill_n(OutputIterator first, Size n, const T& value);
-T   template
-      void generate(ForwardIterator first, ForwardIterator last, Generator gen);
-T   template
-      void generate_n(OutputIterator first, Size n, Generator gen);
-T   template
-      ForwardIterator remove(ForwardIterator first, ForwardIterator last,
-                             const T& value);
-T   template
-      ForwardIterator remove_if(ForwardIterator first, ForwardIterator last,
-                                Predicate pred);
-T   template
-      OutputIterator remove_copy(InputIterator first, InputIterator last,
-                                 OutputIterator result, const T& value);
-T   template
-      OutputIterator remove_copy_if(InputIterator first, InputIterator last,
-                                    OutputIterator result, Predicate pred);
-T   template
-      ForwardIterator unique(ForwardIterator first, ForwardIterator last);
-T   template
-      ForwardIterator unique(ForwardIterator first, ForwardIterator last,
-                             BinaryPredicate pred);
-T   template
-      OutputIterator unique_copy(InputIterator first, InputIterator last,
-                                 OutputIterator result);
-T   template
-      OutputIterator unique_copy(InputIterator first, InputIterator last,
-                                 OutputIterator result, BinaryPredicate pred);
-T   template
-      void reverse(BidirectionalIterator first, BidirectionalIterator last);
-T   template
-      OutputIterator reverse_copy(BidirectionalIterator first,
-                                  BidirectionalIterator last,
-                                  OutputIterator result);
-
-T   template
-      void rotate(ForwardIterator first, ForwardIterator middle,
-                  ForwardIterator last);
-T   template
-      OutputIterator rotate_copy(ForwardIterator first, ForwardIterator middle,
-                                 ForwardIterator last, OutputIterator result);
-T   template
-      void random_shuffle(RandomAccessIterator first,
-                          RandomAccessIterator last);
-T   template
-      void random_shuffle(RandomAccessIterator first,
-                          RandomAccessIterator last,
-                          RandomNumberGenerator& rand);
-    // _lib.alg.partitions_, partitions:
-T   template
-      BidirectionalIterator partition(BidirectionalIterator first,
-                                      BidirectionalIterator last,
-                                      Predicate pred);
-T   template
-      BidirectionalIterator stable_partition(BidirectionalIterator first,
-                                             BidirectionalIterator last,
-                                             Predicate pred);
-    // _lib.alg.sorting_, sorting and related operations:
-    // _lib.alg.sort_, sorting:
-T   template
-      void sort(RandomAccessIterator first, RandomAccessIterator last);
-T   template
-      void sort(RandomAccessIterator first, RandomAccessIterator last,
-                Compare comp);
-T   template
-      void stable_sort(RandomAccessIterator first, RandomAccessIterator last);
-T   template
-      void stable_sort(RandomAccessIterator first, RandomAccessIterator last,
-                       Compare comp);
-T   template
-      void partial_sort(RandomAccessIterator first,
-                        RandomAccessIterator middle,
-                        RandomAccessIterator last);
-T   template
-      void partial_sort(RandomAccessIterator first,
-                        RandomAccessIterator middle,
-                        RandomAccessIterator last, Compare comp);
-T   template
-      RandomAccessIterator
-        partial_sort_copy(InputIterator first, InputIterator last,
-                          RandomAccessIterator result_first,
-                          RandomAccessIterator result_last);
-T   template
-      RandomAccessIterator
-        partial_sort_copy(InputIterator first, InputIterator last,
-                          RandomAccessIterator result_first,
-                          RandomAccessIterator result_last,
-                          Compare comp);
-
-T   template
-      void nth_element(RandomAccessIterator first, RandomAccessIterator nth,
-                       RandomAccessIterator last);
-T   template
-      void nth_element(RandomAccessIterator first, RandomAccessIterator nth,
-                       RandomAccessIterator last, Compare comp);
-    // _lib.alg.binary.search_, binary search:
-T   template
-      ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last,
-                                  const T& value);
-T   template
-      ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last,
-                                  const T& value, Compare comp);
-T   template
-      ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last,
-                                  const T& value);
-T   template
-      ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last,
-                                  const T& value, Compare comp);
-T   template
-      pair
-        equal_range(ForwardIterator first, ForwardIterator last,
-                    const T& value);
-T   template
-      pair
-        equal_range(ForwardIterator first, ForwardIterator last,
-                    const T& value, Compare comp);
-T   template
-      bool binary_search(ForwardIterator first, ForwardIterator last,
-                         const T& value);
-T   template
-      bool binary_search(ForwardIterator first, ForwardIterator last,
-                         const T& value, Compare comp);
-    // _lib.alg.merge_, merge:
-T   template
-      OutputIterator merge(InputIterator1 first1, InputIterator1 last1,
-                           InputIterator2 first2, InputIterator2 last2,
-                           OutputIterator result);
-T   template
-      OutputIterator merge(InputIterator1 first1, InputIterator1 last1,
-                           InputIterator2 first2, InputIterator2 last2,
-                           OutputIterator result, Compare comp);
-T   template
-      void inplace_merge(BidirectionalIterator first,
-                         BidirectionalIterator middle,
-                         BidirectionalIterator last);
-T   template
-      void inplace_merge(BidirectionalIterator first,
-                         BidirectionalIterator middle,
-                         BidirectionalIterator last, Compare comp);
-
-    // _lib.alg.set.operations_, set operations:
-T   template
-      bool includes(InputIterator1 first1, InputIterator1 last1,
-                    InputIterator2 first2, InputIterator2 last2);
-T   template
-      bool includes(InputIterator1 first1, InputIterator1 last1,
-                    InputIterator2 first2, InputIterator2 last2, Compare comp);
-T   template
-      OutputIterator set_union(InputIterator1 first1, InputIterator1 last1,
-                               InputIterator2 first2, InputIterator2 last2,
-                               OutputIterator result);
-T   template
-      OutputIterator set_union(InputIterator1 first1, InputIterator1 last1,
-                               InputIterator2 first2, InputIterator2 last2,
-                               OutputIterator result, Compare comp);
-T   template
-      OutputIterator set_intersection
-          (InputIterator1 first1, InputIterator1 last1,
-           InputIterator2 first2, InputIterator2 last2,
-           OutputIterator result);
-T   template
-      OutputIterator set_intersection
-          (InputIterator1 first1, InputIterator1 last1,
-           InputIterator2 first2, InputIterator2 last2,
-           OutputIterator result, Compare comp);
-T   template
-      OutputIterator set_difference
-          (InputIterator1 first1, InputIterator1 last1,
-           InputIterator2 first2, InputIterator2 last2,
-           OutputIterator result);
-T   template
-      OutputIterator set_difference(InputIterator1 first1, InputIterator1 last1,
-                                    InputIterator2 first2, InputIterator2 last2,
-                                    OutputIterator result, Compare comp);
-T   template
-      OutputIterator
-        set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,
-                                 InputIterator2 first2, InputIterator2 last2,
-                                 OutputIterator result);
-T   template
-      OutputIterator
-        set_symmetric_difference(InputIterator1 first1, InputIterator1 last1,
-                                 InputIterator2 first2, InputIterator2 last2,
-                                 OutputIterator result, Compare comp);
-    // _lib.alg.heap.operations_, heap operations:
-T   template
-      void push_heap(RandomAccessIterator first, RandomAccessIterator last);
-T   template
-      void push_heap(RandomAccessIterator first, RandomAccessIterator last,
-                     Compare comp);
-
-T   template
-      void pop_heap(RandomAccessIterator first, RandomAccessIterator last);
-T   template
-      void pop_heap(RandomAccessIterator first, RandomAccessIterator last,
-                    Compare comp);
-T   template
-      void make_heap(RandomAccessIterator first, RandomAccessIterator last);
-T   template
-      void make_heap(RandomAccessIterator first, RandomAccessIterator last,
-                     Compare comp);
-T   template
-      void sort_heap(RandomAccessIterator first, RandomAccessIterator last);
-T   template
-      void sort_heap(RandomAccessIterator first, RandomAccessIterator last,
-                     Compare comp);
-    // _lib.alg.min.max_, minimum and maximum:
-T   template const T& min(const T& a, const T& b);
-T   template
-      const T& min(const T& a, const T& b, Compare comp);
-T   template const T& max(const T& a, const T& b);
-T   template
-      const T& max(const T& a, const T& b, Compare comp);
-T   template
-      ForwardIterator min_element(ForwardIterator first, ForwardIterator last);
-T   template
-      ForwardIterator min_element(ForwardIterator first, ForwardIterator last,
-                                Compare comp);
-T   template
-      ForwardIterator max_element(ForwardIterator first, ForwardIterator last);
-T   template
-      ForwardIterator max_element(ForwardIterator first, ForwardIterator last,
-                                Compare comp);
-T   template
-      bool lexicographical_compare
-          (InputIterator1 first1, InputIterator1 last1,
-           InputIterator2 first2, InputIterator2 last2);
-T   template
-      bool lexicographical_compare
-          (InputIterator1 first1, InputIterator1 last1,
-           InputIterator2 first2, InputIterator2 last2,
-           Compare comp);
-
-    // _lib.alg.permutation.generators_, permutations
-T   template
-      bool next_permutation(BidirectionalIterator first,
-                            BidirectionalIterator last);
-T   template
-      bool next_permutation(BidirectionalIterator first,
-                            BidirectionalIterator last, Compare comp);
-T   template
-      bool prev_permutation(BidirectionalIterator first,
-                            BidirectionalIterator last);
-T   template
-      bool prev_permutation(BidirectionalIterator first,
-                            BidirectionalIterator last, Compare comp);
-
-
-   25.4  C library algorithms                         [lib.alg.c.library]
-
-   1 Header  (partial, Table 2):
-
-                    Table 2--Header  synopsis
-
-                      Functions:   bsearch   qsort
-
-
-X  extern "C" void *bsearch(const void *key, const void *base,
-                          size_t nmemb, size_t size,
-                          int (*compar)(const void *, const void *));
-X  extern "C++" void *bsearch(const void *key, const void *base,
-                          size_t nmemb, size_t size,
-                          int (*compar)(const void *, const void *));
-
-X  extern "C" void qsort(void* base, size_t nmemb, size_t size,
-                  int (*compar)(const void*, const void*));
-X  extern "C++" void qsort(void* base, size_t nmemb, size_t size,
-                  int (*compar)(const void*, const void*));
-
-
-
-   26.2  Complex numbers                            [lib.complex.numbers]
-
-
-   26.2.1  Header  synopsis               [lib.complex.synopsis]
-
-T   template class complex;
-T   template<> class complex;
-T   template<> class complex;
-T   template<> class complex;
-    // _lib.complex.ops_ operators:
-T   template
-      complex operator+(const complex&, const complex&);
-T   template complex operator+(const complex&, const T&);
-T   template complex operator+(const T&, const complex&);
-T   template complex operator-
-      (const complex&, const complex&);
-T   template complex operator-(const complex&, const T&);
-T   template complex operator-(const T&, const complex&);
-T   template complex operator*
-      (const complex&, const complex&);
-T   template complex operator*(const complex&, const T&);
-T   template complex operator*(const T&, const complex&);
-T   template complex operator/
-      (const complex&, const complex&);
-T   template complex operator/(const complex&, const T&);
-T   template complex operator/(const T&, const complex&);
-T   template complex operator+(const complex&);
-T   template complex operator-(const complex&);
-T   template bool operator==
-      (const complex&, const complex&);
-T   template bool operator==(const complex&, const T&);
-T   template bool operator==(const T&, const complex&);
-T   template bool operator!=(const complex&, const complex&);
-T   template bool operator!=(const complex&, const T&);
-T   template bool operator!=(const T&, const complex&);
-T   template
-      basic_istream&
-      operator>>(basic_istream&, complex&);
-
-T   template
-      basic_ostream&
-      operator<<(basic_ostream&, const complex&);
-    // _lib.complex.value.ops_ values:
-T   template T real(const complex&);
-T   template T imag(const complex&);
-
-T   template T abs(const complex&);
-T   template T arg(const complex&);
-T   template T norm(const complex&);
-T   template complex conj(const complex&);
-T   template complex polar(const T&, const T&);
-    // _lib.complex.transcendentals_ transcendentals:
-T   template complex cos  (const complex&);
-T   template complex cosh (const complex&);
-T   template complex exp  (const complex&);
-T   template complex log  (const complex&);
-T   template complex log10(const complex&);
-T   template complex pow(const complex&, int);
-T   template complex pow(const complex&, const T&);
-T   template complex pow(const complex&, const complex&);
-T   template complex pow(const T&, const complex&);
-T   template complex sin  (const complex&);
-T   template complex sinh (const complex&);
-T   template complex sqrt (const complex&);
-T   template complex tan  (const complex&);
-T   template complex tanh (const complex&);
-   }
-
-   26.2.2  Template class complex                           [lib.complex]
-
-    template
-T   class complex {
-    public:
-T     typedef T value_type;
-
-T     complex(const T& re = T(), const T& im = T());
-T     complex(const complex&);
-T     template complex(const complex&);
-
-T     T real() const;
-T     T imag() const;
-
-T     complex& operator= (const T&);
-T     complex& operator+=(const T&);
-T     complex& operator-=(const T&);
-T     complex& operator*=(const T&);
-T     complex& operator/=(const T&);
-
-T     complex& operator=(const complex&);
-T     template complex& operator= (const complex&);
-T     template complex& operator+=(const complex&);
-T     template complex& operator-=(const complex&);
-T     template complex& operator*=(const complex&);
-T     template complex& operator/=(const complex&);
-    };
-
-T   template complex operator+
-      (const complex&, const complex&);
-T   template complex operator+(const complex&, const T&);
-T   template complex operator+(const T&, const complex&);
-
-T   template complex operator-
-      (const complex&, const complex&);
-T   template complex operator-(const complex&, const T&);
-T   template complex operator-(const T&, const complex&);
-
-T   template complex operator*
-      (const complex&, const complex&);
-T   template complex operator*(const complex&, const T&);
-T   template complex operator*(const T&, const complex&);
-
-T   template complex operator/
-      (const complex&, const complex&);
-T   template complex operator/(const complex&, const T&);
-T   template complex operator/(const T&, const complex&);
-
-T   template complex operator+(const complex&);
-T   template complex operator-(const complex&);
-
-T   template bool operator==(const complex&, const complex&);
-T   template bool operator==(const complex&, const T&);
-T   template bool operator==(const T&, const complex&);
-
-T   template bool operator!=(const complex&, const complex&);
-T   template bool operator!=(const complex&, const T&);
-T   template bool operator!=(const T&, const complex&);
-
-T   template
-      basic_istream&
-      operator>>(basic_istream&, complex&);
-
-T   template
-      basic_ostream&
-      operator<<(basic_ostream&, const complex&);
-
-
-   26.2.3  complex specializations                  [lib.complex.special]
-
-T   template<> class complex {
-    public:
-T     typedef float value_type;
-
-T     complex(float re = 0.0f, float im = 0.0f);
-T     explicit complex(const complex&);
-T     explicit complex(const complex&);
-T     float real() const;
-T     float imag() const;
-
-T     complex& operator= (float);
-T     complex& operator+=(float);
-T     complex& operator-=(float);
-T     complex& operator*=(float);
-T     complex& operator/=(float);
-
-T     complex& operator=(const complex&);
-T     template complex& operator= (const complex&);
-T     template complex& operator+=(const complex&);
-T     template complex& operator-=(const complex&);
-T     template complex& operator*=(const complex&);
-T     template complex& operator/=(const complex&);
-    };
-T   template<> class complex {
-    public:
-T     typedef double value_type;
-
-T     complex(double re = 0.0, double im = 0.0);
-T     complex(const complex&);
-T     explicit complex(const complex&);
-T     double real() const;
-T     double imag() const;
-
-T     complex& operator= (double);
-T     complex& operator+=(double);
-T     complex& operator-=(double);
-T     complex& operator*=(double);
-T     complex& operator/=(double);
-
-T     complex& operator=(const complex&);
-T     template complex& operator= (const complex&);
-T     template complex& operator+=(const complex&);
-T     template complex& operator-=(const complex&);
-T     template complex& operator*=(const complex&);
-T     template complex& operator/=(const complex&);
-    };
-
-T   template<> class complex {
-    public:
-T     typedef long double value_type;
-
-T     complex(long double re = 0.0L, long double im = 0.0L);
-T     complex(const complex&);
-T     complex(const complex&);
-T     long double real() const;
-T     long double imag() const;
-
-T     complex& operator=(const complex&);
-T     complex& operator= (long double);
-T     complex& operator+=(long double);
-T     complex& operator-=(long double);
-T     complex& operator*=(long double);
-T     complex& operator/=(long double);
-
-T     template complex& operator= (const complex&);
-T     template complex& operator+=(const complex&);
-T     template complex& operator-=(const complex&);
-T     template complex& operator*=(const complex&);
-T     template complex& operator/=(const complex&);
-    };
-
-   26.3  Numeric arrays                                    [lib.numarray]
-
-   26.3.1  Header  synopsis             [lib.valarray.synopsis]
-
-T   template class valarray;         // An array of type T
-T   class slice;
-T   template class slice_array;
-T   class gslice;
-T   template class gslice_array;
-T   template class mask_array;       // a masked array
-T   template class indirect_array;   // an indirected array
-
-T   template valarray operator*
-      (const valarray&, const valarray&);
-T   template valarray operator* (const valarray&, const T&);
-T   template valarray operator* (const T&, const valarray&);
-T   template valarray operator/
-      (const valarray&, const valarray&);
-T   template valarray operator/ (const valarray&, const T&);
-T   template valarray operator/ (const T&, const valarray&);
-T   template valarray operator%
-      (const valarray&, const valarray&);
-T   template valarray operator% (const valarray&, const T&);
-T   template valarray operator% (const T&, const valarray&);
-T   template valarray operator+
-      (const valarray&, const valarray&);
-T   template valarray operator+ (const valarray&, const T&);
-T   template valarray operator+ (const T&, const valarray&);
-T   template valarray operator-
-      (const valarray&, const valarray&);
-T   template valarray operator- (const valarray&, const T&);
-T   template valarray operator- (const T&, const valarray&);
-T   template valarray operator^
-      (const valarray&, const valarray&);
-T   template valarray operator^ (const valarray&, const T&);
-T   template valarray operator^ (const T&, const valarray&);
-T   template valarray operator&
-      (const valarray&, const valarray&);
-T   template valarray operator& (const valarray&, const T&);
-T   template valarray operator& (const T&, const valarray&);
-T   template valarray operator|
-      (const valarray&, const valarray&);
-T   template valarray operator| (const valarray&, const T&);
-T   template valarray operator| (const T&, const valarray&);
-T   template valarray operator<<
-      (const valarray&, const valarray&);
-T   template valarray operator<<(const valarray&, const T&);
-T   template valarray operator<<(const T&, const valarray&);
-T   template valarray operator>>
-      (const valarray&, const valarray&);
-T   template valarray operator>>(const valarray&, const T&);
-T   template valarray operator>>(const T&, const valarray&);
-T   template valarray operator&&
-      (const valarray&, const valarray&);
-T   template valarray operator&&(const valarray&, const T&);
-T   template valarray operator&&(const T&, const valarray&);
-T   template valarray operator||
-      (const valarray&, const valarray&);
-T   template valarray operator||(const valarray&, const T&);
-T   template valarray operator||(const T&, const valarray&);
-
-T   template
-      valarray operator==(const valarray&, const valarray&);
-T   template valarray operator==(const valarray&, const T&);
-T   template valarray operator==(const T&, const valarray&);
-T   template
-      valarray operator!=(const valarray&, const valarray&);
-T   template valarray operator!=(const valarray&, const T&);
-T   template valarray operator!=(const T&, const valarray&);
-T   template
-      valarray operator< (const valarray&, const valarray&);
-T   template valarray operator< (const valarray&, const T&);
-T   template valarray operator< (const T&, const valarray&);
-T   template
-      valarray operator> (const valarray&, const valarray&);
-T   template valarray operator> (const valarray&, const T&);
-T   template valarray operator> (const T&, const valarray&);
-T   template
-      valarray operator<=(const valarray&, const valarray&);
-T   template valarray operator<=(const valarray&, const T&);
-T   template valarray operator<=(const T&, const valarray&);
-T   template
-      valarray operator>=(const valarray&, const valarray&);
-T   template valarray operator>=(const valarray&, const T&);
-T   template valarray operator>=(const T&, const valarray&);
-T   template valarray abs  (const valarray&);
-T   template valarray acos (const valarray&);
-T   template valarray asin (const valarray&);
-T   template valarray atan (const valarray&);
-T   template valarray atan2
-      (const valarray&, const valarray&);
-T   template valarray atan2(const valarray&, const T&);
-T   template valarray atan2(const T&, const valarray&);
-T   template valarray cos  (const valarray&);
-T   template valarray cosh (const valarray&);
-T   template valarray exp  (const valarray&);
-T   template valarray log  (const valarray&);
-T   template valarray log10(const valarray&);
-T   template valarray pow(const valarray&, const valarray&);
-T   template valarray pow(const valarray&, const T&);
-T   template valarray pow(const T&, const valarray&);
-T   template valarray sin  (const valarray&);
-T   template valarray sinh (const valarray&);
-T   template valarray sqrt (const valarray&);
-T   template valarray tan  (const valarray&);
-T   template valarray tanh (const valarray&);
-   }
-
-
-   26.3.2  Template class valarray                [lib.template.valarray]
-
-T   template class valarray {
-    public:
-T     typedef T value_type;
-
-      // _lib.valarray.cons_ construct/destroy:
-T     valarray();
-T     explicit valarray(size_t);
-T     valarray(const T&, size_t);
-T     valarray(const T*, size_t);
-T     valarray(const valarray&);
-T     valarray(const slice_array&);
-T     valarray(const gslice_array&);
-T     valarray(const mask_array&);
-T     valarray(const indirect_array&);
-T    ~valarray();
-
-      // _lib.valarray.assign_ assignment:
-T     valarray& operator=(const valarray&);
-T     valarray& operator=(const T&);
-T     valarray& operator=(const slice_array&);
-T     valarray& operator=(const gslice_array&);
-T     valarray& operator=(const mask_array&);
-T     valarray& operator=(const indirect_array&);
-      // _lib.valarray.access_ element access:
-T     T                 operator[](size_t) const;
-T     T&                operator[](size_t);
-      // _lib.valarray.sub_ subset operations:
-T     valarray       operator[](slice) const;
-T     slice_array    operator[](slice);
-T     valarray       operator[](const gslice&) const;
-T     gslice_array   operator[](const gslice&);
-T     valarray       operator[](const valarray&) const;
-T     mask_array     operator[](const valarray&);
-T     valarray       operator[](const valarray&) const;
-T     indirect_array operator[](const valarray&);
-      // _lib.valarray.unary_ unary operators:
-T     valarray operator+() const;
-T     valarray operator-() const;
-T     valarray operator~() const;
-T     valarray operator!() const;
-      // _lib.valarray.cassign_ computed assignment:
-T     valarray& operator*= (const T&);
-T     valarray& operator/= (const T&);
-T     valarray& operator%= (const T&);
-T     valarray& operator+= (const T&);
-T     valarray& operator-= (const T&);
-T     valarray& operator^= (const T&);
-T     valarray& operator&= (const T&);
-T     valarray& operator|= (const T&);
-T     valarray& operator<<=(const T&);
-T     valarray& operator>>=(const T&);
-T     valarray& operator*= (const valarray&);
-T     valarray& operator/= (const valarray&);
-T     valarray& operator%= (const valarray&);
-T     valarray& operator+= (const valarray&);
-T     valarray& operator-= (const valarray&);
-T     valarray& operator^= (const valarray&);
-T     valarray& operator|= (const valarray&);
-T     valarray& operator&= (const valarray&);
-T     valarray& operator<<=(const valarray&);
-T     valarray& operator>>=(const valarray&);
-      // _lib.valarray.members_ member functions:
-T     size_t size() const;
-T     T    sum() const;
-T     T    min() const;
-T     T    max() const;
-
-T     valarray shift (int) const;
-T     valarray cshift(int) const;
-T     valarray apply(T func(T)) const;
-T     valarray apply(T func(const T&)) const;
-T     void resize(size_t sz, T c = T());
-    };
-   }
-
-
-
-   26.3.4  Class slice                                  [lib.class.slice]
-
-T   class slice {
-    public:
-T     slice();
-T     slice(size_t, size_t, size_t);
-
-T     size_t start() const;
-T     size_t size() const;
-T     size_t stride() const;
-    };
-   }
-
-
-
-   26.3.5  Template class slice_array          [lib.template.slice.array]
-
-T   template  class slice_array {
-    public:
-T     typedef T value_type;
-
-T     void operator=  (const valarray&) const;
-T     void operator*= (const valarray&) const;
-T     void operator/= (const valarray&) const;
-T     void operator%= (const valarray&) const;
-T     void operator+= (const valarray&) const;
-T     void operator-= (const valarray&) const;
-T     void operator^= (const valarray&) const;
-T     void operator&= (const valarray&) const;
-T     void operator|= (const valarray&) const;
-T     void operator<<=(const valarray&) const;
-T     void operator>>=(const valarray&) const;
-T     void operator=(const T&);
-T    ~slice_array();
-    private:
-T     slice_array();
-T     slice_array(const slice_array&);
-T     slice_array& operator=(const slice_array&);
-    };
-   }
-
-
-
-   26.3.6  The gslice class                            [lib.class.gslice]
-
-T   class gslice {
-    public:
-T     gslice();
-T     gslice(size_t s, const valarray& l, const valarray& d);
-
-T     size_t           start() const;
-T     valarray size() const;
-T     valarray stride() const;
-    };
-
-
-   26.3.7  Template class gslice_array        [lib.template.gslice.array]
-
-T   template  class gslice_array {
-    public:
-T     typedef T value_type;
-
-T     void operator=  (const valarray&) const;
-T     void operator*= (const valarray&) const;
-T     void operator/= (const valarray&) const;
-T     void operator%= (const valarray&) const;
-T     void operator+= (const valarray&) const;
-T     void operator-= (const valarray&) const;
-T     void operator^= (const valarray&) const;
-T     void operator&= (const valarray&) const;
-T     void operator|= (const valarray&) const;
-T     void operator<<=(const valarray&) const;
-T     void operator>>=(const valarray&) const;
-T     void operator=(const T&);
-T    ~gslice_array();
-    private:
-T     gslice_array();
-T     gslice_array(const gslice_array&);
-T     gslice_array& operator=(const gslice_array&);
-    };
-
-
-   26.3.8  Template class mask_array            [lib.template.mask.array]
-
-T   template  class mask_array {
-    public:
-T     typedef T value_type;
-
-T     void operator=  (const valarray&) const;
-T     void operator*= (const valarray&) const;
-T     void operator/= (const valarray&) const;
-T     void operator%= (const valarray&) const;
-T     void operator+= (const valarray&) const;
-T     void operator-= (const valarray&) const;
-T     void operator^= (const valarray&) const;
-T     void operator&= (const valarray&) const;
-T     void operator|= (const valarray&) const;
-T     void operator<<=(const valarray&) const;
-T     void operator>>=(const valarray&) const;
-T     void operator=(const T&);
-T    ~mask_array();
-    private:
-T     mask_array();
-T     mask_array(const mask_array&);
-T     mask_array& operator=(const mask_array&);
-      //  remainder implementation defined
-    };
-
-
-   26.3.9  Template class                   [lib.template.indirect.array]
-       indirect_array
-
-T   template  class indirect_array {
-    public:
-T     typedef T value_type;
-
-T     void operator=  (const valarray&) const;
-T     void operator*= (const valarray&) const;
-T     void operator/= (const valarray&) const;
-T     void operator%= (const valarray&) const;
-T     void operator+= (const valarray&) const;
-T     void operator-= (const valarray&) const;
-T     void operator^= (const valarray&) const;
-T     void operator&= (const valarray&) const;
-T     void operator|= (const valarray&) const;
-T     void operator<<=(const valarray&) const;
-T     void operator>>=(const valarray&) const;
-T     void operator=(const T&);
-T    ~indirect_array();
-    private:
-T     indirect_array();
-T     indirect_array(const indirect_array&);
-T     indirect_array& operator=(const indirect_array&);
-      //  remainder implementation defined
-    };
-
-   26.4  Generalized numeric operations                 [lib.numeric.ops]
-
-   Header  synopsis
-
-T   template 
-      T accumulate(InputIterator first, InputIterator last, T init);
-
-T   template 
-      T accumulate(InputIterator first, InputIterator last, T init,
-                   BinaryOperation binary_op);
-
-T   template 
-      T inner_product(InputIterator1 first1, InputIterator1 last1,
-                      InputIterator2 first2, T init);
-
-T   template 
-      T inner_product(InputIterator1 first1, InputIterator1 last1,
-                      InputIterator2 first2, T init,
-                      BinaryOperation1 binary_op1,
-                      BinaryOperation2 binary_op2);
-
-T   template 
-      OutputIterator partial_sum(InputIterator first,
-                                 InputIterator last,
-                                 OutputIterator result);
-
-T   template 
-      OutputIterator partial_sum(InputIterator first,
-                                 InputIterator last,
-                                 OutputIterator result,
-                                 BinaryOperation binary_op);
-
-T   template 
-      OutputIterator adjacent_difference(InputIterator first,
-                                         InputIterator last,
-                                         OutputIterator result);
-
-T   template 
-      OutputIterator adjacent_difference(InputIterator first,
-                                         InputIterator last,
-                                         OutputIterator result,
-                                         BinaryOperation binary_op);
-
-
-   26.5  C Library                                           [lib.c.math]
-
-                     Table 2--Header  synopsis
-X               Macro:   HUGE_VAL
-                Functions:
-X               acos     cos        fmod    modf   tan
-X               asin     cosh       frexp   pow    tanh
-X               atan     exp        ldexp   sin
-X               atan2    fabs       log     sinh
-X               ceil     floor      log10   sqrt
-
-                    Table 3--Header  synopsis
-X                     Macros:   RAND_MAX
-X                     Types:    div_t      ldiv_t
-                      Functions:
-X                     abs       labs       srand
-X                     div       ldiv       rand
-
-X  long   abs(long);               // labs()
-X  ldiv_t div(long, long);         // ldiv()
-
-X  float abs  (float);
-X  float acos (float);
-X  float asin (float);
-X  float atan (float);
-X  float atan2(float, float);
-X  float ceil (float);
-X  float cos  (float);
-X  float cosh (float);
-X  float exp  (float);
-X  float fabs (float);
-X  float floor(float);
-X  float fmod (float, float);
-X  float frexp(float, int*);
-X  float ldexp(float, int);
-X  float log  (float);
-X  float log10(float);
-X  float modf (float, float*);
-X  float pow  (float, float);
-X  float pow  (float, int);
-X  float sin  (float);
-X  float sinh (float);
-X  float sqrt (float);
-X  float tan  (float);
-X  float tanh (float);
-
-X  double abs(double);            // fabs()
-X  double pow(double, int);
-
-X  long double abs  (long double);
-X  long double acos (long double);
-X  long double asin (long double);
-X  long double atan (long double);
-X  long double atan2(long double, long double);
-X  long double ceil (long double);
-X  long double cos  (long double);
-X  long double cosh (long double);
-X  long double exp  (long double);
-X  long double fabs (long double);
-X  long double floor(long double);
-X  long double fmod (long double, long double);
-X  long double frexp(long double, int*);
-X  long double ldexp(long double, int);
-X  long double log  (long double);
-X  long double log10(long double);
-X  long double modf (long double, long double*);
-X  long double pow  (long double, long double);
-X  long double pow  (long double, int);
-X  long double sin  (long double);
-X  long double sinh (long double);
-X  long double sqrt (long double);
-X  long double tan  (long double);
-X  long double tanh (long double);
-
-   Header  synopsis
-
-X   template class char_traits;
-X   template<> class char_traits;
-X   template<> class char_traits;
-X   template class allocator;
-X   template  >
-      class basic_ios;
-
-X   template  >
-      class basic_streambuf;
-
-X   template  >
-      class basic_istream;
-
-X   template  >
-      class basic_ostream;
-
-X   template  >
-      class basic_iostream;
-
-X   template ,
-              class Allocator = allocator >
-      class basic_stringbuf;
-
-X   template ,
-              class Allocator = allocator >
-      class basic_istringstream;
-
-X   template ,
-              class Allocator = allocator >
-      class basic_ostringstream;
-
-X   template ,
-              class Allocator = allocator >
-      class basic_stringstream;
-
-X   template  >
-      class basic_filebuf;
-
-X   template  >
-      class basic_ifstream;
-
-X   template  >
-      class basic_ofstream;
-
-X   template  >
-      class basic_fstream;
-X   template  >
-      class istreambuf_iterator;
-
-X   template  >
-      class ostreambuf_iterator;
-X   typedef basic_ios       ios;
-X   typedef basic_ios    wios;
-X   typedef basic_streambuf streambuf;
-X   typedef basic_istream   istream;
-X   typedef basic_ostream   ostream;
-X   typedef basic_iostream  iostream;
-X   typedef basic_stringbuf     stringbuf;
-X   typedef basic_istringstream istringstream;
-X   typedef basic_ostringstream ostringstream;
-X   typedef basic_stringstream  stringstream;
-X   typedef basic_filebuf  filebuf;
-X   typedef basic_ifstream ifstream;
-X   typedef basic_ofstream ofstream;
-X   typedef basic_fstream  fstream;
-X   typedef basic_streambuf wstreambuf;
-X   typedef basic_istream   wistream;
-X   typedef basic_ostream   wostream;
-X   typedef basic_iostream  wiostream;
-X   typedef basic_stringbuf     wstringbuf;
-X   typedef basic_istringstream wistringstream;
-X   typedef basic_ostringstream wostringstream;
-X   typedef basic_stringstream  wstringstream;
-
-X   typedef basic_filebuf  wfilebuf;
-X   typedef basic_ifstream wifstream;
-X   typedef basic_ofstream wofstream;
-X   typedef basic_fstream  wfstream;
-X   template  class fpos;
-X   typedef fpos::state_type>    streampos;
-X   typedef fpos::state_type> wstreampos;
-
-   27.3  Standard iostream objects                 [lib.iostream.objects]
-
-   Header  synopsis
-
-T  [must also include  and ]
-T   extern istream cin;
-T   extern ostream cout;
-T   extern ostream cerr;
-T   extern ostream clog;
-
-T   extern wistream wcin;
-T   extern wostream wcout;
-T   extern wostream wcerr;
-T   extern wostream wclog;
-
-   27.4  Iostreams base classes                      [lib.iostreams.base]
-
-   Header  synopsis
-
-   #include 
-
-T   typedef OFF_T  streamoff;
-T   typedef SZ_T streamsize;
-T   template  class fpos;
-
-    class ios_base;
-    template  >
-      class basic_ios;
-   // _lib.std.ios.manip_, manipulators:
-T   ios_base& boolalpha  (ios_base& str);
-T   ios_base& noboolalpha(ios_base& str);
-T   ios_base& showbase   (ios_base& str);
-T   ios_base& noshowbase (ios_base& str);
-T   ios_base& showpoint  (ios_base& str);
-T   ios_base& noshowpoint(ios_base& str);
-T   ios_base& showpos    (ios_base& str);
-T   ios_base& noshowpos  (ios_base& str);
-T   ios_base& skipws     (ios_base& str);
-T   ios_base& noskipws   (ios_base& str);
-T   ios_base& nouppercase(ios_base& str);
-T   ios_base& uppercase  (ios_base& str);
-M   ios_base& unitbuf    (ios_base& str);
-M   ios_base& nounitbuf  (ios_base& str);
-   // _lib.adjustfield.manip_ adjustfield:
-T   ios_base& internal   (ios_base& str);
-T   ios_base& left       (ios_base& str);
-T   ios_base& right      (ios_base& str);
-   // _lib.basefield.manip_ basefield:
-T   ios_base& dec        (ios_base& str);
-T   ios_base& hex        (ios_base& str);
-T   ios_base& oct        (ios_base& str);
-
-   // _lib.floatfield.manip_ floatfield:
-T   ios_base& fixed      (ios_base& str);
-T   ios_base& scientific (ios_base& str);
-
-
-   27.4.2  Class ios_base                                  [lib.ios.base]
-
-T   class ios_base {
-    public:
-      class failure;
-T     typedef T1 fmtflags;
-T     static const fmtflags boolalpha;
-T     static const fmtflags dec;
-T     static const fmtflags fixed;
-T     static const fmtflags hex;
-T     static const fmtflags internal;
-T     static const fmtflags left;
-T     static const fmtflags oct;
-T     static const fmtflags right;
-T     static const fmtflags scientific;
-T     static const fmtflags showbase;
-T     static const fmtflags showpoint;
-T     static const fmtflags showpos;
-T     static const fmtflags skipws;
-X     static const fmtflags unitbuf;
-T     static const fmtflags uppercase;
-T     static const fmtflags adjustfield;
-T     static const fmtflags basefield;
-T     static const fmtflags floatfield;
-
-      typedef T2 iostate;
-T     static const iostate badbit;
-T     static const iostate eofbit;
-T     static const iostate failbit;
-T     static const iostate goodbit;
-T     typedef T3 openmode;
-T     static const openmode app;
-T     static const openmode ate;
-T     static const openmode binary;
-T     static const openmode in;
-T     static const openmode out;
-T     static const openmode trunc;
-T     typedef T4 seekdir;
-T     static const seekdir beg;
-T     static const seekdir cur;
-T     static const seekdir end;
-T     class Init;
-      // _lib.fmtflags.state_ fmtflags state:
-T     fmtflags flags() const;
-T     fmtflags flags(fmtflags fmtfl);
-T     fmtflags setf(fmtflags fmtfl);
-T     fmtflags setf(fmtflags fmtfl, fmtflags mask);
-T     void unsetf(fmtflags mask);
-T     streamsize precision() const;
-T     streamsize precision(streamsize prec);
-T     streamsize width() const;
-T     streamsize width(streamsize wide);
-      // _lib.ios.base.locales_ locales:
-T     locale imbue(const locale& loc);
-T     locale getloc() const;
-      // _lib.ios.base.storage_ storage:
-T     static int xalloc();
-T     long&  iword(int index);
-T     void*& pword(int index);
-      // destructor
-T     virtual ~ios_base();
-      // _lib.ios.base.callback_ callbacks;
-T     enum event { erase_event, imbue_event, copyfmt_event };
-T     typedef void (*event_callback)(event, ios_base&, int index);
-T     void register_callback(event_call_back fn, int index);
-T     static bool sync_with_stdio(bool sync = true);
-    protected:
-T     ios_base();
-    };
-
-   27.4.2.1.1  Class ios_base::failure                 [lib.ios::failure]
-
-T   class ios_base::failure : public exception {
-    public:
-T     explicit failure(const string& msg);
-T     virtual ~failure();
-T     virtual const char* what() const throw();
-    };
-
-
-   27.4.2.1.6  Class ios_base::Init                       [lib.ios::Init]
-
-T   class ios_base::Init {
-    public:
-T     Init();
-T    ~Init();
-    };
-
-
-   27.4.3  Template class fpos                                 [lib.fpos]
-
-X   template  class fpos {
-    public:
-      // _lib.fpos.members_ Members
-T     stateT state() const;
-T     void state(stateT);
-    private;
-T     stateT st; // exposition only
-    };
-
-
-   27.4.5  Template class basic_ios                             [lib.ios]
-
-    template  >
-X   class basic_ios : public ios_base {
-    public:
-
-      // Types:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-T     operator void*() const
-T     bool operator!() const
-T     iostate rdstate() const;
-T     void clear(iostate state = goodbit);
-T     void setstate(iostate state);
-T     bool good() const;
-T     bool eof()  const;
-T     bool fail() const;
-T     bool bad()  const;
-T     iostate exceptions() const;
-T     void exceptions(iostate except);
-      // _lib.basic.ios.cons_ Constructor/destructor:
-T     explicit basic_ios(basic_streambuf* sb);
-T     virtual ~basic_ios();
-      // _lib.basic.ios.members_ Members:
-T     basic_ostream* tie() const;
-T     basic_ostream* tie(basic_ostream* tiestr);
-T     basic_streambuf* rdbuf() const;
-T     basic_streambuf* rdbuf(basic_streambuf* sb);
-X     basic_ios& copyfmt(const basic_ios& rhs);
-T     char_type fill() const;
-T     char_type fill(char_type ch);
-      // _lib.ios.base.locales_ locales:
-T     locale imbue(const locale& loc);
-X     char     narrow(char_type c, char dfault) const;
-X     char_type widen(char c) const;
-    protected:
-      basic_ios();
-T     void init(basic_streambuf* sb);
-   private:
-T     basic_ios(const basic_ios& );       // not defined
-T     basic_ios& operator=(const basic_ios&);     // not defined
-    };
-
-
-   27.5  Stream buffers                              [lib.stream.buffers]
-
-   Header  synopsis
-
-X   template  >
-      class basic_streambuf;
-T   typedef basic_streambuf     streambuf;
-T   typedef basic_streambuf wstreambuf;
-
-   27.5.2  Template class                                 [lib.streambuf]
-       basic_streambuf
-
-    template  >
-X   class basic_streambuf {
-    public:
-
-      // Types:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-T     virtual ~basic_streambuf();
-      // _lib.streambuf.locales_ locales:
-T     locale   pubimbue(const locale &loc);
-T     locale   getloc() const;
-      // _lib.streambuf.buffer_ buffer and positioning:
-T     basic_streambuf*
-               pubsetbuf(char_type* s, streamsize n);
-T     pos_type pubseekoff(off_type off, ios_base::seekdir way,
-                          ios_base::openmode which =
-                              ios_base::in | ios_base::out);
-T     pos_type pubseekpos(pos_type sp,
-                          ios_base::openmode which =
-                              ios_base::in | ios_base::out);
-T     int      pubsync();
-
-      // Get and put areas:
-      // _lib.streambuf.pub.get_ Get area:
-T     streamsize in_avail();
-T     int_type snextc();
-T     int_type sbumpc();
-T     int_type sgetc();
-T     streamsize sgetn(char_type* s, streamsize n);
-      // _lib.streambuf.pub.pback_ Putback:
-X     int_type sputbackc(char_type c);
-X     int_type sungetc();
-      // _lib.streambuf.pub.put_ Put area:
-T     int_type   sputc(char_type c);
-X     streamsize sputn(const char_type* s, streamsize n);
-    protected:
-T     basic_streambuf();
-      // _lib.streambuf.get.area_ Get area:
-T     char_type* eback() const;
-T     char_type* gptr()  const;
-T     char_type* egptr() const;
-T     void       gbump(int n);
-T     void       setg(char_type* gbeg, char_type* gnext, char_type* gend);
-      // _lib.streambuf.put.area_ Put area:
-T     char_type* pbase() const;
-T     char_type* pptr() const;
-T     char_type* epptr() const;
-T     void       pbump(int n);
-T     void       setp(char_type* pbeg, char_type* pend);
-      // _lib.streambuf.virtuals_ virtual functions:
-      // _lib.streambuf.virt.locales_ Locales:
-T     virtual void imbue(const locale &loc);
-      // _lib.streambuf.virt.buffer_ Buffer management and positioning:
-T     virtual basic_streambuf*
-                       setbuf(char_type* s, streamsize n);
-T     virtual pos_type seekoff(off_type off, ios_base::seekdir way,
-                ios_base::openmode which = ios_base::in | ios_base::out);
-T     virtual pos_type seekpos(pos_type sp,
-                ios_base::openmode which = ios_base::in | ios_base::out);
-T     virtual int      sync();
-      // _lib.streambuf.virt.get_ Get area:
-T     virtual int        showmanyc();
-T     virtual streamsize xsgetn(char_type* s, streamsize n);
-T     virtual int_type   underflow();
-T     virtual int_type   uflow();
-      // _lib.streambuf.virt.pback_ Putback:
-T     virtual int_type   pbackfail(int_type c = traits::eof());
-      // _lib.streambuf.virt.put_ Put area:
-X     virtual streamsize xsputn(const char_type* s, streamsize n);
-T     virtual int_type   overflow (int_type c = traits::eof());
-    };
-
-   27.6  Formatting and manipulators                [lib.iostream.format]
-
-   Header  synopsis
-
-T   template  >
-      class basic_istream;
-T   typedef basic_istream     istream;
-T   typedef basic_istream wistream;
-
-T   template  >
-      class basic_iostream;
-T   typedef basic_iostream    iostream;
-T   typedef basic_iostream wiostream;
-
-X   template 
-      basic_istream& ws(basic_istream& is);
-
-   Header  synopsis
-
-X   template  >
-      class basic_ostream;
-T   typedef basic_ostream     ostream;
-T   typedef basic_ostream wostream;
-
-T   template 
-      basic_ostream& endl(basic_ostream& os);
-T   template 
-      basic_ostream& ends(basic_ostream& os);
-T   template 
-      basic_ostream& flush(basic_ostream& os);
-
-   Header  synopsis
-
-      // Types T1, T2, ... are unspecified implementation types
-T     T1 resetiosflags(ios_base::fmtflags mask);
-T     T2 setiosflags  (ios_base::fmtflags mask);
-T     T3 setbase(int base);
-T     template T4 setfill(charT c);
-T     T5 setprecision(int n);
-T     T6 setw(int n);
-
-
-   27.6.1.1  Template class basic_istream                   [lib.istream]
-
-    template  >
-T   class basic_istream : virtual public basic_ios {
-    public:
-    // Types (inherited from basic_ios (_lib.ios_)):
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // _lib.istream.cons_ Constructor/destructor:
-T     explicit basic_istream(basic_streambuf* sb);
-T     virtual ~basic_istream();
-      // _lib.istream::sentry_ Prefix/suffix:
-T     class sentry;
-
-      // _lib.istream.formatted_ Formatted input:
-T     basic_istream& operator>>
-          (basic_istream& (*pf)(basic_istream&))
-T     basic_istream& operator>>
-          (basic_ios& (*pf)(basic_ios&))
-T     basic_istream& operator>>
-          (ios_base& (*pf)(ios_base&))
-S     basic_istream& operator>>(bool& n);
-S     basic_istream& operator>>(short& n);
-S     basic_istream& operator>>(unsigned short& n);
-S     basic_istream& operator>>(int& n);
-S     basic_istream& operator>>(unsigned int& n);
-S     basic_istream& operator>>(long& n);
-S     basic_istream& operator>>(unsigned long& n);
-S     basic_istream& operator>>(float& f);
-S     basic_istream& operator>>(double& f);
-S     basic_istream& operator>>(long double& f);
-S     basic_istream& operator>>(void*& p);
-S     basic_istream& operator>>
-          (basic_streambuf* sb);
-      // _lib.istream.unformatted_ Unformatted input:
-T     streamsize gcount() const;
-S     int_type get();
-S     basic_istream& get(char_type& c);
-S     basic_istream& get(char_type* s, streamsize n);
-S     basic_istream& get(char_type* s, streamsize n,
-                        char_type delim);
-S     basic_istream& get(basic_streambuf& sb);
-S     basic_istream& get(basic_streambuf& sb,
-                        char_type delim);
-S     basic_istream& getline(char_type* s, streamsize n);
-S     basic_istream& getline(char_type* s, streamsize n,
-                        char_type delim);
-S     basic_istream& ignore
-          (streamsize n = 1, int_type delim = traits::eof());
-S     int_type                     peek();
-S     basic_istream& read    (char_type* s, streamsize n);
-S     streamsize                   readsome(char_type* s, streamsize n);
-S     basic_istream& putback(char_type c);
-S     basic_istream& unget();
-S     int sync();
-
-S     pos_type tellg();
-S     basic_istream& seekg(pos_type);
-S     basic_istream& seekg(off_type, ios_base::seekdir);
-    };
-
-    // _lib.istream::extractors_ character extraction templates:
-S   template
-      basic_istream& operator>>(basic_istream&,
-                                              charT&);
-S   template
-      basic_istream& operator>>(basic_istream&,
-                                             unsigned char&);
-S   template
-      basic_istream& operator>>(basic_istream&,
-                                             signed char&);
-
-S   template
-      basic_istream& operator>>(basic_istream&,
-                                              charT*);
-S   template
-      basic_istream& operator>>(basic_istream&,
-                                             unsigned char*);
-S   template
-      basic_istream& operator>>(basic_istream&,
-                                             signed char*);
-
-   27.6.1.1.2  Class basic_istream::sentry          [lib.istream::sentry]
-
-
-    template  >
-S   class basic_istream::sentry {
-      typedef traits traits_type;
-S     bool ok_; // exposition only
-     public:
-S     explicit sentry(basic_istream& is, bool noskipws = false);
-S     ~sentry();
-S     operator bool() const { return ok_; }
-     private:
-T     sentry(const sentry&); //   not defined
-T     sentry& operator=(const sentry&); //   not defined
-    };
-
-
-   27.6.1.5  Template class basic_iostream            [lib.iostreamclass]
-
-    template  >
-T   class basic_iostream :
-      public basic_istream,
-      public basic_ostream {
-    public:
-      // constructor/destructor
-T     explicit basic_iostream(basic_streambuf* sb);
-T     virtual ~basic_iostream();
-    };
-
-
-   27.6.2.1  Template class basic_ostream                   [lib.ostream]
-
-    template  >
-X   class basic_ostream : virtual public basic_ios {
-    public:
-    // Types (inherited from basic_ios (_lib.ios_)):
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // _lib.ostream.cons_ Constructor/destructor:
-T     explicit basic_ostream(basic_streambuf* sb);
-T     virtual ~basic_ostream();
-      // _lib.ostream::sentry_ Prefix/suffix:
-T     class sentry;
-      // _lib.ostream.formatted_ Formatted output:
-T     basic_ostream& operator<<
-          (basic_ostream& (*pf)(basic_ostream&));
-T     basic_ostream& operator<<
-          (basic_ios& (*pf)(basic_ios&));
-T     basic_ostream& operator<<
-          (ios_base& (*pf)(ios_base&));
-T     basic_ostream& operator<<(bool n);
-T     basic_ostream& operator<<(short n);
-T     basic_ostream& operator<<(unsigned short n);
-T     basic_ostream& operator<<(int n);
-T     basic_ostream& operator<<(unsigned int n);
-T     basic_ostream& operator<<(long n);
-T     basic_ostream& operator<<(unsigned long n);
-S     basic_ostream& operator<<(float f);
-S     basic_ostream& operator<<(double f);
-S     basic_ostream& operator<<(long double f);
-T     basic_ostream& operator<<(const void* p);
-X     basic_ostream& operator<<
-          (basic_streambuf* sb);
-      // _lib.ostream.unformatted_ Unformatted output:
-T     basic_ostream& put(char_type c);
-T     basic_ostream& write(const char_type* s, streamsize n);
-X     basic_ostream& flush();
-
-      // _lib.ostream.seeks_ seeks:
-S     pos_type tellp();
-S     basic_ostream& seekp(pos_type);
-S     basic_ostream& seekp(off_type, ios_base::seekdir);
-    };
-    // _lib.ostream.inserters.character_ character inserters
-X   template
-    basic_ostream& operator<<(basic_ostream&,
-                                            charT);
-X   template
-    basic_ostream& operator<<(basic_ostream&,
-                                            char);
-    // specialization
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                             char);
-    // signed and unsigned
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                             signed char);
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                             unsigned char)
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                              const charT*);
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                              const char*);
-    // partial specializationss
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                             const char*);
-    //  signed and unsigned
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                             const signed char*);
-X   template
-      basic_ostream& operator<<(basic_ostream&,
-                                             const unsigned char*);
-
-
-   27.6.2.3  Class basic_ostream::sentry            [lib.ostream::sentry]
-
-    template  >
-X   class basic_ostream::sentry {
-      bool ok_; // exposition only
-     public:
-X     explicit sentry(basic_ostream& os);
-X     ~sentry();
-X     operator bool() const { return ok_; }
-     private
-X     sentry(const sentry&); //   not defined
-X     sentry& operator=(const sentry&); //   not defined
-    };
-
-   27.7  String-based streams                        [lib.string.streams]
-
-   Header  synopsis
-
-X   template ,
-                      class Allocator = allocator >
-      class basic_stringbuf;
-
-T   typedef basic_stringbuf     stringbuf;
-T   typedef basic_stringbuf wstringbuf;
-
-    template ,
-                      class Allocator = allocator >
-X     class basic_istringstream;
-
-T   typedef basic_istringstream     istringstream;
-T   typedef basic_istringstream wistringstream;
-
-    template ,
-                      class Allocator = allocator >
-X     class basic_ostringstream;
-T   typedef basic_ostringstream     ostringstream;
-T   typedef basic_ostringstream wostringstream;
-
-    template ,
-                      class Allocator = allocator >
-X     class basic_stringstream;
-T   typedef basic_stringstream     stringstream;
-T   typedef basic_stringstream wstringstream;
-
-   27.7.1  Template class basic_stringbuf                 [lib.stringbuf]
-
-    template ,
-              class Allocator = allocator >
-X   class basic_stringbuf : public basic_streambuf {
-    public:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // _lib.stringbuf.cons_ Constructors:
-S     explicit basic_stringbuf(ios_base::openmode which
-                                = ios_base::in | ios_base::out);
-S     explicit basic_stringbuf
-          (const basic_string& str,
-           ios_base::openmode which = ios_base::in | ios_base::out);
-      // _lib.stringbuf.members_ Get and set:
-S     basic_string str() const;
-S     void               str(const basic_string& s);
-
-    protected:
-      // _lib.stringbuf.virtuals_ Overridden virtual functions:
-S     virtual int_type   underflow();
-S     virtual int_type   pbackfail(int_type c = traits::eof());
-S     virtual int_type   overflow (int_type c = traits::eof());
-S     virtual  basic_streambuf* setbuf(charT*, streamsize);
-
-S     virtual pos_type   seekoff(off_type off, ios_base::seekdir way,
-                                 ios_base::openmode which
-                                  = ios_base::in | ios_base::out);
-S     virtual pos_type   seekpos(pos_type sp,
-                                 ios_base::openmode which
-                                  = ios_base::in | ios_base::out);
-    };
-
-
-   27.7.2  Template class basic_istringstream         [lib.istringstream]
-
-    template ,
-              class Allocator = allocator >
-X   class basic_istringstream : public basic_istream {
-    public:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // _lib.istringstream.cons_ Constructors:
-S     explicit basic_istringstream(ios_base::openmode which = ios_base::in);
-S     explicit basic_istringstream(
-                         const basic_string& str,
-                         ios_base::openmode which = ios_base::in);
-
-      // _lib.istringstream.members_ Members:
-S     basic_stringbuf* rdbuf() const;
-S     basic_string str() const;
-S     void str(const basic_string& s);
-   private:
-   //  basic_stringbuf sb;   exposition only
-    };
-
-   27.7.3  Class basic_ostringstream                  [lib.ostringstream]
-
-    template ,
-              class Allocator = allocator >
-X   class basic_ostringstream : public basic_ostream {
-    public:
-
-      // Types:
-T     typedef charT            char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-      // _lib.ostringstream.cons_ Constructors/destructor:
-S     explicit basic_ostringstream(ios_base::openmode which = ios_base::out);
-S     explicit basic_ostringstream(
-                           const basic_string& str,
-                           ios_base::openmode which = ios_base::out);
-      // _lib.ostringstream.members_ Members:
-S     basic_stringbuf* rdbuf() const;
-S     basic_string str() const;
-S     void    str(const basic_string& s);
-    };
-
-
-   27.7.4  Template class basic_stringstream           [lib.stringstream]
-
-    template ,
-              class Allocator = allocator >
-X   class basic_stringstream
-      : public basic_iostream {
-    public:
-      // Types
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-      // constructors/destructors
-S     explicit basic_stringstream(
-          ios_base::openmode which = ios_base::out|ios_base::in);
-S     explicit basic_stringstream(
-          const basic_string& str,
-          ios_base::openmode which = ios_base::out|ios_base::in);
-      // Members:
-S     basic_stringbuf* rdbuf() const;
-S     basic_string str() const;
-S     void str(const basic_string& str);
-    };
-
-
-
-   27.8.1  File streams                                    [lib.fstreams]
-
-
-   Header  synopsis
-
-X   template  >
-      class basic_filebuf;
-T   typedef basic_filebuf    filebuf;
-T   typedef basic_filebuf wfilebuf;
-
-X   template  >
-      class basic_ifstream;
-T   typedef basic_ifstream    ifstream;
-T   typedef basic_ifstream wifstream;
-
-X   template  >
-      class basic_ofstream;
-T   typedef basic_ofstream    ofstream;
-T   typedef basic_ofstream wofstream;
-
-X   template  >
-      class basic_fstream;
-T   typedef basic_fstream     fstream;
-T   typedef basic_fstream wfstream;
-
-   27.8.1.1  Template class basic_filebuf                   [lib.filebuf]
-
-    template  >
-X   class basic_filebuf : public basic_streambuf {
-    public:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // _lib.filebuf.cons_ Constructors/destructor:
-X     basic_filebuf();
-X     virtual ~basic_filebuf();
-       // _lib.filebuf.members_ Members:
-T     bool is_open() const;
-X     basic_filebuf* open
-          (const char* s, ios_base::openmode mode);
-X     basic_filebuf* close();
-    protected:
-      // _lib.filebuf.virtuals_ Overridden virtual functions:
-X     virtual streamsize showmanyc();
-X     virtual int_type underflow();
-X     virtual int_type uflow();
-X     virtual int_type pbackfail(int_type c = traits::eof());
-X     virtual int_type overflow (int_type c = traits::eof());
-S     virtual basic_streambuf*
-                       setbuf(char_type* s, streamsize n);
-S     virtual pos_type seekoff(off_type off, ios_base::seekdir way,
-                               ios_base::openmode which
-                                 = ios_base::in | ios_base::out);
-S     virtual pos_type seekpos(pos_type sp, ios_base::openmode which
-                                 = ios_base::in | ios_base::out);
-S     virtual int      sync();
-S     virtual void     imbue(const locale& loc);
-    };
-
-
-
-   27.8.1.5  Template class basic_ifstream                 [lib.ifstream]
-
-    template  >
-X   class basic_ifstream : public basic_istream {
-    public:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // _lib.ifstream.cons_ Constructors:
-S     basic_ifstream();
-S     explicit basic_ifstream(const char* s,
-                              ios_base::openmode mode = ios_base::in);
-      // _lib.ifstream.members_ Members:
-S     basic_filebuf* rdbuf() const;
-S     bool is_open();
-S     void open(const char* s, ios_base::openmode mode = ios_base::in);
-S     void close();
-    };
-
-
-   27.8.1.8  Template class basic_ofstream                 [lib.ofstream]
-
-    template  >
-X   class basic_ofstream : public basic_ostream {
-    public:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // _lib.ofstream.cons_ Constructors:
-X     basic_ofstream();
-X     explicit basic_ofstream(const char* s,
-                              ios_base::openmode mode
-                                = ios_base::out);
-      // _lib.ofstream.members_ Members:
-X     basic_filebuf* rdbuf() const;
-T     bool is_open();
-X     void open(const char* s, ios_base::openmode mode = ios_base::out);
-X     void close();
-    };
-
-
-   27.8.1.11  Template class basic_fstream                  [lib.fstream]
-
-    template  >
-X   class basic_fstream
-      : public basic_iostream {
-    public:
-T     typedef charT                     char_type;
-T     typedef typename traits::int_type int_type;
-T     typedef typename traits::pos_type pos_type;
-T     typedef typename traits::off_type off_type;
-T     typedef traits                    traits_type;
-      // constructors/destructor
-S     basic_fstream();
-S     explicit basic_fstream(
-          const char* s,
-          ios_base::openmode mode = ios_base::in|ios_base::out);
-
-      // Members:
-S     basic_filebuf* rdbuf() const;
-S     bool is_open();
-S     void open(
-          const char* s,
-          ios_base::openmode mode = ios_base::in|ios_base::out);
-S     void close();
-    };
-
-
-
-   27.8.2  C Library files                                  [lib.c.files]
-
-
-                    Table 13--Header  synopsis
-    Macros:
-X   BUFSIZ         L_tmpnam        SEEK_SET   TMP_MAX
-X   EOF            NULL    stderr     _IOFBF
-X   FILENAME_MAX   SEEK_CUR        stdin      _IOLBF
-X   FOPEN_MAX      SEEK_END        stdout     _IONBF
-
-X   Types:         FILE            fpos_t     size_t 
-    Functions:
-X   clearerr       fgets           fscanf     gets     rewind
-X   fclose         fopen           fseek      perror   scanf     tmpnam
-X   feof           fprintf         fsetpos    printf   setbuf    ungetc
-X   ferror         fputc           ftell      putc     setvbuf   vprintf
-X   fflush         fputs           fwrite     puts     sprintf   vfprintf
-X   fgetc          fread           getc       remove   sscanf    vsprintf
-X   fgetpos        freopen         getchar    putchar  rename    tmpfile
-
-
-
-
-   1.5  Standard C library headers                       [depr.c.headers]
-
-X                  
-                   
-                
-                  
-
-   1.6  Old iostreams members                          [depr.ios.members]
-
-   [Note: these should be #ifdef'd to permit diagnostics if used.]
-   namespace std {
-    class ios_base {
-    public:
-T     typedef T1  io_state;
-T     typedef T2 open_mode;
-T     typedef T3  seek_dir;
-T     typedef OFF_T  streamoff;
-T     typedef OFF_T  streampos;
-      // remainder unchanged
-    };
-   }
-
-   [Note: these should be #ifdef'd to permit diagnostics if used.]
-   namespace std {
-    template >
-    class basic_streambuf {
-    public:
-T     void stossc();
-      // remainder unchanged
-    };
-   }
-
-   8 An implementation may provide  the  following  member  functions  that
-   overload signatures specified in clause _lib.iostreams_:
-
-   [Note: the following overloads should be #ifdef'd to permit
-    diagnostics to be emitted, by default, if used.]
-
-    template class basic_ios {
-    public:
-M     void clear(io_state state);
-M     void setstate(io_state state);
-      // remainder unchanged
-    };
-    class ios_base {
-    public:
-M     void exceptions(io_state);
-      // remainder unchanged
-    };
-    template >
-    class basic_streambuf {
-    public:
-M     pos_type pubseekoff(off_type off, ios_base::seek_dir way,
-                ios_base::open_mode which = ios_base::in | ios_base::out);
-M     pos_type pubseekpos(pos_type sp,
-                ios_base::open_mode which = ios_base::in | ios_base::out);
-      // remainder unchanged
-    };
-    template  >
-    class basic_filebuf : public basic_streambuf {
-    public:
-M     basic_filebuf* open
-          (const char* s, ios_base::open_mode mode);
-      // remainder unchanged
-    };
-    template  >
-    class basic_ifstream : public basic_istream {
-    public:
-M     void open(const char* s, ios_base::open_mode mode = in);
-      // remainder unchanged
-    };
-    template  >
-    class basic_ofstream : public basic_ostream {
-    public:
-M     void open(const char* s, ios_base::open_mode mode = out | trunc);
-      // remainder unchanged
-    };
-   }
-
-
-
-   1.7.1  Class strstreambuf                          [depr.strstreambuf]
-
-   [Note: It should be possible to adopt these components with only
-    minor changes from the 2.8 version of the library.]
-
-M   class strstreambuf : public basic_streambuf {
-    public:
-M     explicit strstreambuf(streamsize alsize_arg = 0);
-M     strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));
-M     strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0);
-M     strstreambuf(const char* gnext_arg, streamsize n);
-M     strstreambuf(signed char* gnext_arg, streamsize n,
-                   signed char* pbeg_arg = 0);
-M     strstreambuf(const signed char* gnext_arg, streamsize n);
-M     strstreambuf(unsigned char* gnext_arg, streamsize n,
-                   unsigned char* pbeg_arg = 0);
-M     strstreambuf(const unsigned char* gnext_arg, streamsize n);
-M     virtual ~strstreambuf();
-M     void  freeze(bool freezefl = true);
-M     char* str();
-M     int   pcount();
-    protected:
-M     virtual int_type overflow (int_type c = EOF);
-M     virtual int_type pbackfail(int_type c = EOF);
-M     virtual int_type underflow();
-M     virtual pos_type seekoff(off_type off, ios_base::seekdir way,
-                               ios_base::openmode which
-                                = ios_base::in | ios_base::out);
-M     virtual pos_type seekpos(pos_type sp, ios_base::openmode which
-                                = ios_base::in | ios_base::out);
-M     virtual streambuf* setbuf(char* s, streamsize n);
-   }
-
-   1.7.4  Class strstream                                [depr.strstream]
-
-M   class strstream
-      : public basic_iostream {
-    public:
-      // Types
-M     typedef char                                char_type;
-M     typedef typename char_traits::int_type int_type
-M     typedef typename char_traits::pos_type pos_type;
-M     typedef typename char_traits::off_type off_type;
-      // consturctors/destructor
-M     strstream();
-M     strstream(char* s, int n,
-                ios_base::openmode mode = ios_base::in|ios_base::out);
-M     virtual ~strstream();
-      // Members:
-M     strstreambuf* rdbuf() const;
-M     void freeze(bool freezefl = true);
-M     int pcount() const;
-M     char* str();
-    };
-
-
\ No newline at end of file diff --git a/libstdc++-v3/doc/html/17_intro/confdeps.dot b/libstdc++-v3/doc/html/17_intro/confdeps.dot deleted file mode 100644 index a62d28ce9ddf..000000000000 --- a/libstdc++-v3/doc/html/17_intro/confdeps.dot +++ /dev/null @@ -1,14 +0,0 @@ -# Blatantly ripped out of the graphviz examples and modified. -pme -digraph v3conf { - size="6,6"; - node [color=lightblue2, style=filled]; - "aclocal.m4" -> "acinclude.m4"; - "configure" -> "aclocal.m4"; - "configure" -> "configure.ac"; - "configure" -> "crossconfig.m4"; - "configure" -> "linkage.m4"; - "[*/]Makefile.in" -> "Makefile.am"; - "[*/]Makefile.in" -> "configure.ac"; - "config.h.in" -> "acconfig.h"; - "config.h.in" -> "configure.ac"; -} diff --git a/libstdc++-v3/doc/html/17_intro/confdeps.png b/libstdc++-v3/doc/html/17_intro/confdeps.png deleted file mode 100644 index 5075aa869b158b79a04a48023f24817743615807..0000000000000000000000000000000000000000 GIT binary patch literal 0 Hc-jL100001 literal 3486 zc-o~`X*3iH8x?DBFvD1f!j-*blASCS#y0k4l*vvqp({j5l-(V& zS8fy8GN>>ZOJU}7@Bi>y{KgZPLJdHls$rD|@SMXP)Hz5lPLkhk zW9v>-Ahvz{ILC;$rT-Ri#+?0ch=&gI71g(5iZB$5G`}pRCDKhd+tOxx$pOwMVyKK% z&wO&Xe7s@WAYAS26I*!Mx&-1;NZ{pk?nn6Z@zefN0s@ILc>zg% zJ`_~s=}Zmf-Yx}(2aT*mg{CA+I(ot4mAZ~l#EfA~U|hQ~Kj^HY5*V4+n7VA0bCuA~ zQO&Vfh4J-p&Ye8_*hLcrR~!qzppfcjosfaEBhjQtYy$#0)?XUc$q{C8N|;CqRs}Fj zSSoUUNx=B_VZ&@{wNSfZe>Pr_(R$soo2RnO?%|>r)PSZU4rrW9Sz$~GM$=M8#43jN zB`YgpO7uf2lAD;p_!ZxLMI+l!<;4&`Uk*b0DmhyX=ZPsBoBJV!4c+0sJKe-AqKslB z)++ZAui{r3QQ)WEn3$EnFTYy8zuywN@Vcy{Q0~-MtxJBm6a#oQF<`MbCOjfOh~44M zUXCHc{OPBG(bL|QA z?Ski$X?EzV2}MG8-q~yhedCyvD)o#e1gRbJ6SNe-5i}W*z*Cav7V1IIPQ=3^k0bGJ zEjExt$PL{6fzkHuVsMVS9uF^ccdRTi7`@LWnO)hPaTP$+7&L2t5H;c1A>YR#6wY-o z=y0QhZG#2_0av{W7h;*tuA;gzcHAIc-wcZCoxtwjiptfN4>e!XMXr^b-JRGuG!g=w zaWULrmF6?PXvr_;7V!ayFVIb%flD4P_0Sgj=+FprrD<{PNH^F83|zlXz6a%LbI;-; z?lN_9%5I+TGO@WN0E!7Op1ZhVXwb8`SDNb@6Hd%bED8+^r`CH1N>dBr8{Km5^)8zNMnGWK>(q-`DRf{` z6*xy2yIHIWd!!1+e$ZHrz(i4uFGQZ7>h;;x-7?uKatc9VO64RwnM)^vpeAz|K$)|DhZ1JfT z_P9T;J3NezM~6k9u+fV*9J%ny?OfZ-kWlqr4p-~W7Vg-4*kQGH%?Csx1T+?cmkqm( z%A@q%-wsyq<8ZOw8p@(99+o{hhoyb<$>3=yX0x>WVby7o2NUgyf%77UX*shR0on<%ckR{X=`uND083Tr(MKnVI0WU2mmsP(YDrjt zJRFa1EcQu zOPdCTE_eIT@1JvFL_urJYu^#a%Ut8pEuBd7b*|a(i`70^eig~(O#0(@mm$!aWIlP0 z7{+(!Z37voXb688fkP0f|C_XF8{|AVn`q9;7s$04Pfpbkjyb$x4N%owS8>sFf`(_G%Z zX#T2Dzi*rNxcjh3V&zS<{1+f{hRcVU4AouO-9tj^;lik^ro!aF8h-3e?hj~BKf5>F z=^Hk>SL3K_0yA~)7T^a{|Y1q$ixB(bA?x%^Ze zVxdaaWnCmC-vk3|NkJ_kKxr34m4BrBO~BCWH$v?{#(NwGE`v+c>DWMK^!=DYnozrj zjI-X)+&Sjbfg$GN0lCD7pLw2ZaxLn^U+G`uGSu{~MIUvZL}Ar6;RmB%0%l?dyAn+v z-}ksPQ}ku8`GvGtLBj?eikuk^`W$I2YRUUoBA7(mY}A$27sx&uTb)YD1l~uv92M^b z3P;s8PQl-c$sVcKvb1rBQ&F;cbF?}^KPSy_B5Xff(h}yB!NdjiYzRHHkmDRc%P{8a z?`XAxtSHbCX79$d;tyqjm2q}M32nS!)uvhFy}WWo!LvsgN$U?Y`~~-92J+a|=NB0` z-q|@QLqCjZO~oNeC?Tk6X&O}lmQsOcBC_O)QqA_~7fA!#kT-?D*PiAAUm2bbl|rI} z;tT~SC_JR_JFx6UAxf!HLl-%tyQcDeJgGQ-=$ch-psV&HDC8`l6tUV(6Tfu#qRFzV zU!AyjVO|fzo^InXs3H3{yQ4Ai7dUq$jG`HI4vcCAjpVdlYUl4S#YDz@% zbQK2$C)GkvRCp+s!{c5(t21-3vwpPlJ?3C(ul(S8q#>zU8VocqS*g*+=?EVspG@I& zd)~pyIqNrC{q@h);KgzTz|skIT54Sn6jd^&Bixibxf|{gbs7P3(wp%ktoI1u_Z`Ey(Mcu0VtplMS}klO0I2^TZ}8~P7PuEp zB%@;cuRMC)qDOkE+tJ67*T*qY@6oi;y;Qj&JCl{3=B@r3atBbW z4%!8M`%|@s*IU$>+MQOb0@}2v_Ty`nL7Y`hKnEnO2J&F2rjT?t-(txDjR`$nExJdx z@M5=D4n{bN0K#AoT8nE5ewp)dW^S`>BoWk%`{0t(k2W zcAT(2@U>~)3f)5d{4reAG_y19H&lh_8>i=jH a>*Vt#|7pGHivq{r6B`<7ZCY>af&UN7iDila diff --git a/libstdc++-v3/doc/html/17_intro/configury.html b/libstdc++-v3/doc/html/17_intro/configury.html deleted file mode 100644 index a35ccf23996b..000000000000 --- a/libstdc++-v3/doc/html/17_intro/configury.html +++ /dev/null @@ -1,305 +0,0 @@ - - - - - - - - - - libstdc++ configury - - - - - -

> open configury door

-

> look

- -

You are in a maze of twisty passages, all -different.

-

It is dark. You are likely to be eaten by a -Canadian cross build.

- - -
-

Notes on libstdc++ configury

-
-No problem is insoluble in all conceivable circumstances.
--- The Cosmic AC, -The -Last Question, by Isaac Asimov -
- - -
-

Prerequisites for configure and make hacking

- -

As -noted previously, -certain other tools are necessary for hacking on files that control -configure (configure.ac, acinclude.m4) and -make (Makefile.am). These additional tools -(automake, and autoconf) are further -described in detail in their respective manuals. All the libraries in GCC try to stay in sync with each other in terms of versions of the auto-tools used, so please try to play nicely with the neighbors. -

- - -
-

Overview: what comes from where

-

Dependency graph in PNG graphics format. (Get a better browser!)

- -

Regenerate all generated files by using the command sequence - "autoreconf" at the top level of the libstdc++ source - directory. The following will also work, but is much more complex: - "aclocal-1.7 && autoconf-2.59 && - autoheader-2.59 && automake-1.7" The version numbers - may be absent entirely or otherwise vary depending on - the current - requirements and your vendor's choice of installation names. -

- - -
-

Storing information in non-AC files, like - configure.host

-

Until that glorious day when we can use AC_TRY_LINK with a cross-compiler, - we have to hardcode the results of what the tests would have shown if - they could be run. So we have an inflexible mess like crossconfig.m4. -

- -

Wouldn't it be nice if we could store that information in files like - configure.host, which can be modified without needing to regenerate - anything, and can even be tweaked without really knowing how the configury - all works? Perhaps break the pieces of crossconfig.m4 out and place them in - their appropriate config/{cpu,os} directory. -

- -

Alas, writing macros like "AC_DEFINE(HAVE_A_NICE_DAY)" can - only be done inside files which are passed through autoconf. Files which - are pure shell script can be source'd at configure time. Files which - contain autoconf macros must be processed with autoconf. We could still - try breaking the pieces out into "config/*/cross.m4" bits, for instance, - but then we would need arguments to aclocal/autoconf to properly find - them all when generating configure. I would discourage that. -

- - -
-

Coding and commenting conventions

-

Lots of stuff got thrown out because the new autotools kindly generate - the same (or better) shell code for us. -

- -

Most comments should use {octothorpes, shibboleths, hash marks, pound - signs, whatevers} rather than "dnl". Nearly all comments in configure.ac - should. Comments inside macros written in ancilliary .m4 files should. - About the only comments which should not use #, but use dnl - instead, are comments outside our own macros in the ancilliary - files. The difference is that # comments show up in configure - (which is most helpful for debugging), while dnl'd lines just vanish. - Since the macros in ancilliary files generate code which appears in odd - places, their "outside" comments tend to not be useful while reading - configure. -

- -

Do not use any $target* variables, such as - $target_alias. The single exception is in configure.ac, - for automake+dejagnu's sake. -

- -

-

- -
-

The acinclude.m4 layout

-

The nice thing about acinclude.m4/aclocal.m4 is that macros aren't actually - performed/called/expanded/whatever here, just loaded. So we can arrange - the contents however we like. As of this writing, acinclude.m4 is arranged - as follows: -

-
-    GLIBCXX_CHECK_HOST
-    GLIBCXX_TOPREL_CONFIGURE
-    GLIBCXX_CONFIGURE
-
-

All the major variable "discovery" is done here. CXX, multilibs, etc. -

-
-    fragments included from elsewhere
-
-

Right now, "fragments" == "the math/linkage bits". -

-
-    GLIBCXX_CHECK_COMPILER_FEATURES
-    GLIBCXX_CHECK_LINKER_FEATURES
-    GLIBCXX_CHECK_WCHAR_T_SUPPORT
-
-

Next come extra compiler/linker feature tests. Wide character support - was placed here because I couldn't think of another place for it. It will - probably get broken apart like the math tests, because we're still disabling - wchars on systems which could actually support them. -

-
-    GLIBCXX_CHECK_SETRLIMIT_ancilliary
-    GLIBCXX_CHECK_SETRLIMIT
-    GLIBCXX_CHECK_S_ISREG_OR_S_IFREG
-    GLIBCXX_CHECK_POLL
-    GLIBCXX_CHECK_WRITEV
-
-    GLIBCXX_CONFIGURE_TESTSUITE
-
-

Feature tests which only get used in one place. Here, things used only in - the testsuite, plus a couple bits used in the guts of I/O. -

-
-    GLIBCXX_EXPORT_INCLUDES
-    GLIBCXX_EXPORT_FLAGS
-    GLIBCXX_EXPORT_INSTALL_INFO
-
-

Installation variables, multilibs, working with the rest of the compiler. - Many of the critical variables used in the makefiles are set here. -

-
-    GLIBGCC_ENABLE
-    GLIBCXX_ENABLE_C99
-    GLIBCXX_ENABLE_CHEADERS
-    GLIBCXX_ENABLE_CLOCALE
-    GLIBCXX_ENABLE_CONCEPT_CHECKS
-    GLIBCXX_ENABLE_CSTDIO
-    GLIBCXX_ENABLE_CXX_FLAGS
-    GLIBCXX_ENABLE_C_MBCHAR
-    GLIBCXX_ENABLE_DEBUG
-    GLIBCXX_ENABLE_DEBUG_FLAGS
-    GLIBCXX_ENABLE_LONG_LONG
-    GLIBCXX_ENABLE_PCH
-    GLIBCXX_ENABLE_SJLJ_EXCEPTIONS
-    GLIBCXX_ENABLE_SYMVERS
-    GLIBCXX_ENABLE_THREADS
-
-

All the features which can be controlled with enable/disable configure - options. Note how they're alphabetized now? Keep them like that. :-) -

-
-    AC_LC_MESSAGES
-    libtool bits
-
-

Things which we don't seem to use directly, but just has to be present - otherwise stuff magically goes wonky. -

- - -
-

GLIBCXX_ENABLE, the --enable howto

-

All the GLIBCXX_ENABLE_FOO macros use a common helper, GLIBCXX_ENABLE. - (You don't have to use it, but it's easy.) The helper does two things - for us: -

- -
    -
  1. Builds the call to the AC_ARG_ENABLE macro, with --help text properly - quoted and aligned. (Death to changequote!)
    2. -
  2. Checks the result against a list of allowed possibilities, and signals - a fatal error if there's no match. This means that the rest of the - GLIBCXX_ENABLE_FOO macro doesn't need to test for strange arguments, - nor do we need to protect against empty/whitespace strings with the - "x$foo" = "xbar" idiom.
    3. -
- -

Doing these things correctly takes some extra autoconf/autom4te code, - which made our macros nearly illegible. So all the ugliness is factored - out into this one helper macro. -

- -

Many of the macros take an argument, passed from when they are expanded - in configure.ac. The argument controls the default value of the - enable/disable switch. Previously, the arguments themselves had defaults. - Now they don't, because that's extra complexity with zero gain for us. -

- -

There are three "overloaded signatures". When reading the descriptions - below, keep in mind that the brackets are autoconf's quotation characters, - and that they will be stripped. Examples of just about everything occur - in acinclude.m4, if you want to look. -

- -
-    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING)
-    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)
-    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)
-
- -
    -

  • FEATURE is the string that follows --enable. The results of the test - (such as it is) will be in the variable $enable_FEATURE, where FEATURE - has been squashed. Example: [extra-foo], controlled by the - --enable-extra-foo option and stored in $enable_extra_foo.

    • -

  • DEFAULT is the value to store in $enable_FEATURE if the user does not - pass --enable/--disable. It should be one of the permitted values - passed later. Examples: [yes], or [bar], or - [$1] (which passes the argument given to the - GLIBCXX_ENABLE_FOO macro as the default).

    -

    For cases where we need to probe for particular models - of things, it is useful to have an undocumented "auto" value here (see - GLIBCXX_ENABLE_CLOCALE for an example).

    • -

  • HELP-ARG is any text to append to the option string itself in the - --help output. Examples: [] (i.e., an empty string, - which appends nothing), - [=BAR], which produces - --enable-extra-foo=BAR, and - [@<:@=BAR@:>@], which produces - --enable-extra-foo[=BAR]. See the difference? See what - it implies to the user?

    -

    If you're wondering what that line noise in the last example was, - that's how you embed autoconf special characters in output text. - They're called -quadrigraphs - and you should use them whenever necessary.

    • -

  • HELP-STRING is what you think it is. Do not include the "default" - text like we used to do; it will be done for you by GLIBCXX_ENABLE. - By convention, these are not full English sentences. - Example: [turn on extra foo]

    • -
- -

With no other arguments, only the standard autoconf patterns are - allowed: "--{enable,disable}-foo[={yes,no}]" The - $enable_FEATURE variable is guaranteed to equal either "yes" or "no" - after the macro. If the user tries to pass something else, an - explanatory error message will be given, and configure will halt. -

- -

The second signature takes a fifth argument, - "[permit a|b|c|...]" - This allows a or b or ... after the equals sign in the - option, and $enable_FEATURE is guaranteed to equal one of them after the - macro. Note that if you want to allow plain --enable/--disable with no - "=whatever", you must include "yes" and "no" in the list of permitted - values. Also note that whatever you passed as DEFAULT must be in the list. - If the user tries to pass something not on the list, a semi-explanatory - error message will be given, and configure will halt. - Example: [permit generic|gnu|ieee_1003.1-2001|yes|no|auto] -

- -

The third signature takes a fifth argument. It is arbitrary shell code - to execute if the user actually passes the enable/disable option. (If - the user does not, the default is used. Duh.) No argument checking at - all is done in this signature. See GLIBCXX_ENABLE_CXX_FLAGS for an - example of handling, and an error message. -

- -
- - diff --git a/libstdc++-v3/doc/html/17_intro/contribute.html b/libstdc++-v3/doc/html/17_intro/contribute.html deleted file mode 100644 index 00c749a44907..000000000000 --- a/libstdc++-v3/doc/html/17_intro/contribute.html +++ /dev/null @@ -1,135 +0,0 @@ - - - - - - How to contribute - - - - - - - -

How to contribute

-

The Standard C++ Library v3, follows an open development -model. Active contributors are assigned maintainer-ship -responsibility, and given write access to the SVN repository. First -time 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 -line via the ISO mirror site for committee members. Non-members, or -those who have not paid for the privilege of sitting on the committee -and sustained their two meeting commitment for voting rights, may get -a copy of the standard from their respective national standards -organization. In the USA, this national standards organization is ANSI -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 here: - http://www.open-std.org/jtc1/sc22/wg21 -
    • - -
  • 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 -file. New code and additions to the library need completed copyright -assignment form on file at the FSF. Note: your employer may be required -to fill out appropriate disclaimer forms as well. -

- -

Historically, the libstdc++ assignment form added the following question: -

- -[Which Belgian comic book character is better, Tintin or -Asterix, and why?] - -

-While not strictly necessary, humoring the maintainers and answering -this question would be appreciated. -

- -

-For more information about getting a copyright assignment, please see -Legal -Matters. -

- -

-Please contact Benjamin -Kosnik if you are confused about the assignment or have general -licensing questions. When requesting an assignment form from assign@gnu.org, please cc -the above libstdc++ maintainer so that progress can be monitored. -

- - -
-

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.
    • - -
  • A ChangeLog entry as plain text; 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.
    • - -
  • A testsuite submission or sample program that will easily and - simply show the existing error or test new functionality.
    • - -
  • The patch itself. If you are accessing the SVN repository - use "svn update; svn diff NEW"; else, use "diff -cp OLD NEW" - ... If your version of diff does not support these options, then - get the latest version of GNU diff. The SVN Tricks wiki page - has information on customising the output of svn 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++ mailing list.
    • - -
- - - - diff --git a/libstdc++-v3/doc/html/17_intro/howto.html b/libstdc++-v3/doc/html/17_intro/howto.html deleted file mode 100644 index 09f1a3c370ad..000000000000 --- a/libstdc++-v3/doc/html/17_intro/howto.html +++ /dev/null @@ -1,737 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 17: Library Introduction - - - - - - - - -

Chapter 17: Library Introduction

- -

Chapter 17 is actually a list of definitions and descriptions used - in the following chapters of the Standard when describing the actual - library. Here, we use "Introduction" as an introduction - to the GNU implementation of the ISO Standard C++ Library. -

- - - -
-

Contents

- - -
- - - -

Header Files

-

The C++ standard specifies the entire set of header files that must be - available to all hosted implementations. Actually, the word - "files" is a misnomer, since the contents of the headers - don't necessarily have to be in any kind of external file. The - only rule is that when one #include's a header, the - contents of that header become - available, no matter how. -

- -

That said, in practice files are used.

- -

There are two main types of include files: header files related to -a specific version of the ISO C++ standard (called Standard Headers), -and all others (TR1, C++ ABI, and Extensions).

- -

Two dialects of standard headers are supported, corresponding to -the 1998 standard as updated for 2003, and the draft of the upcoming -200x standard. -

- -

C++98/03 include files. These are available in the default compilation mode, ie -std=c++98 or -std=gnu++98. -

- -
- - - - - - - -
C++98 Library Headers
<algorithm><iomanip><list><ostream><streambuf>
<bitset><ios><locale><queue><string>
<complex><iosfwd><map><set><typeinfo>
<deque><iostream><memory><sstream><utility>
<exception><istream><new><stack><valarray>
<fstream><iterator><numeric><stdexcept><vector>
<functional><limits>
- -

- -
- - - - -
C++98 Headers for C Library Facilities
<cassert><ciso646><csetjmp><cstdio><ctime>
<cctype><climits><csignal><cstdlib><cwchar>
<cerrno><clocale><cstdarg><cstring><cwctype>
<cfloat><cmath><cstddef>
- -

C++0x include files. These are only available in C++0x compilation mode, ie -std=c++0x or -std=gnu++0x. -

- -
- - - - - - - - -
C++0x Library Headers
<algorithm><iomanip><locale><regex><tuple>
<array><ios><map><set><typeinfo>
<bitset><iosfwd><memory><sstream><type_traits>
<complex><iostream><new><stack><unordered_map>
<deque><istream><numeric><stdexcept><unordered_set>
<exception><iterator><ostream><streambuf><utility>
<fstream><limits><queue><string><valarray>
<functional><list><random><system_error><vector>
- -

- -
- - - - - -
C++0x Headers for C Library Facilities
<cassert><cfloat><cmath><cstddef><ctgmath>
<ccomplex><cinttypes><csetjmp><cstdint><ctime>
<cctype><ciso646><csignal><cstdio><cuchar>
<cerrno><climits><cstdarg><cstdlib><cwchar>
<cfenv><clocale><cstdbool><cstring><cwctype>
- - -

In addition, TR1 includes as: -

- -
- - - -
TR1 Library Headers
<tr1/array><tr1/memory><tr1/regex><tr1/type_traits><tr1/unordered_set>
<tr1/complex><tr1/random><tr1/tuple><tr1/unordered_map><tr1/utility>
<tr1/functional>
- -

- -
- - - -
TR1 Headers for C Library Facilities
<tr1/cmath><tr1/cfloat><tr1/cstdarg><tr1/cstdio><tr1/ctime>
<tr1/ccomplex><tr1/cinttypes><tr1/cstdbool><tr1/cstdlib><tr1/cwchar>
<tr1/cfenv><tr1/climits><tr1/cstdint><tr1/ctgmath><tr1/cwctype>
- -

Also included are files for the C++ ABI interface: -

-
- -
C++ ABI Headers
<cxxabi.h><cxxabi_forced.h>
- -

And a large variety of extensions. -

- -
- - - - - - -
Extension Headers
<ext/algorithm><ext/debug_allocator.h><ext/mt_allocator.h><ext/pod_char_traits.h><ext/stdio_sync_filebuf.h>
<ext/array_allocator.h><ext/enc_filebuf.h><ext/new_allocator.h><ext/pool_allocator.h><ext/throw_allocator.h>
<ext/atomicity.h><ext/functional><ext/numeric><ext/rb_tree><ext/typelist.h>
<ext/bitmap_allocator.h><ext/iterator><ext/numeric_traits.h><ext/rope><ext/type_traits.h>
<ext/codecvt_specializations.h><ext/malloc_allocator.h><ext/pb_ds/assoc_container.h><ext/slist><ext/vstring.h>
<ext/concurrence.h><ext/memory><ext/pb_ds/priority_queue.h><ext/stdio_filebuf.h>
- -

- -
- - -
Extension Debug Headers
<debug/bitset><debug/list><debug/set><debug/unordered_map><debug/vector>
<debug/deque><debug/map><debug/string><debug/unordered_set>
- -

- -
- -
Extension Parallel Headers
<parallel/algorithm><parallel/numeric>
- -
-

Recipes for mixing headers

- -

A few simple rules. -

- -

First, mixing different dialects of the standard headers is not -possible. It's an all-or-nothing affair. Thus, code like -

- -
-#include <array>
-#include <functional>
-
- -

Implies C++0x mode. To use the entities in <array>, the C++0x -compilation mode must be used, which implies the C++0x functionality -(and deprecations) in <functional> will be present. -

- -

Second, the other headers can be included with either dialect of -the standard headers, although features and types specific to C++0x -are still only enabled when in C++0x compilation mode. So, to use -rvalue references with __gnu_cxx::vstring, or to use the -debug-mode versions of std::unordered_map, one must use -the std=gnu++0x compiler flag. (Or std=c++0x, of course.) -

- -

A special case of the second rule is the mixing of TR1 and C++0x -facilities. It is possible (although not especially prudent) to -include both the TR1 version and the C++0x version of header in the -same translation unit: -

- -
-#include <tr1/type_traits>
-#include <type_traits>
-
- -

Several parts of C++0x diverge quite substantially from TR1 predecessors. -

- - -
-

The C Headers and namespace std

-

- The standard specifies that if one includes the C-style header - (<math.h> in this case), the symbols will be available - in the global namespace and perhaps in - namespace std:: (but this is no longer a firm - requirement.) One the other hand, including the C++-style - header (<cmath>) guarantees that the entities will be - found in namespace std and perhaps in the global namespace. -

- -

-Usage of C++-style headers is recommended, as then -C-linkage names can be disambiguated by explicit qualification, such -as by std::abort. In addition, the C++-style headers can -use function overloading to provide a simpler interface to certain -families of C-functions. For instance in <cmath>, the -function std::sin has overloads for all the builtin -floating-point types. This means that std::sin can be -used uniformly, instead of a combination -of std::sinf, std::sin, -and std::sinl. -

- -
-

Precompiled Headers

- -

There are three base header files that are provided. They can be -used to precompile the standard headers and extensions into binary -files that may the be used to speed compiles that use these headers. -

- - -
    -
  • stdc++.h -

    Includes all standard headers. Actual content varies depending on -language dialect. -

    -
    • - -
  • stdtr1c++.h -

    Includes all of <stdc++.h>, and adds all the TR1 headers. -

    -
    • - -
  • extc++.h -

    Includes all of <stdtr1c++.h>, and adds all the Extension headers. -

    • -
- -

How to construct a .gch file from one of these base header files.

- -

First, find the include directory for the compiler. One way to do -this is:

- -
-g++ -v hello.cc
-
-#include <...> search starts here:
- /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
-...
-End of search list.
-
- - -

Then, create a precompiled header file with the same flags that -will be used to compile other projects.

- -
-g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h
-
- -

The resulting file will be quite large: the current size is around -thirty megabytes.

- -

How to use the resulting file.

- -
-g++ -I. -include stdc++.h  -H -g -O2 hello.cc 
-
- -

Verification that the PCH file is being used is easy:

- -
-g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
-! ./stdc++.h.gch
-. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
-. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
-
- -

The exclamation point to the left of the stdc++.h.gch listing means that the generated PCH file was used, and thus the

-

- -

Detailed information about creating precompiled header files can be found in the GCC documentation. -

- - -
-

Namespaces

- - -

There are three main namespaces. -

- -
    -
  • std -

    The ISO C++ standards specify that "all library entities are defined -within namespace std." This includes namepaces nested -within namespace std, such as namespace -std::tr1. -

    -
    • -
  • abi -

    Specified by the C++ ABI. This ABI specifies a number of type and -function APIs supplemental to those required by the ISO C++ Standard, -but necessary for interoperability. -

    -
    • - -
  • __gnu_ -

    Indicating one of several GNU extensions. Choices -include __gnu_cxx, __gnu_debug, __gnu_parallel, -and __gnu_pbds. -

    • -
- -

A complete list of implementation namespaces (including namespace contents) is available in the generated source documentation. -

- - -
-

Namespace std::

- -

- One standard requirement is that the library components are defined - in namespace std::. Thus, in order to use these types or - functions, one must do one of two things: -

- -

  • put a kind of -using-declaration in your source -(either using namespace std; or i.e. using -std::string;) This approach works well for individual source files, but -should not be used in a global context, like header files. -

  • use a fully -qualified name for each library symbol -(i.e. std::string, std::cout) Always can be -used, and usually enhanced, by strategic use of typedefs. (In the -cases where the qualified verbiage becomes unwieldy.) -

    • -
- -
-

Using namespace composition

- -

-Best practice in programming suggests sequestering new data or -functionality in a sanely-named, unique namespace whenever -possible. This is considered an advantage over dumping everything in -the global namespace, as then name look-up can be explicitly enabled or -disabled as above, symbols are consistently mangled without repetitive -naming prefixes or macros, etc. -

- -

For instance, consider a project that defines most of its classes in namespace gtk. It is possible to - adapt namespace gtk to namespace std by using a C++-feature called - namespace composition. This is what happens if - a using-declaration is put into a - namespace-definition: the imported symbol(s) gets imported into the - currently active namespace(s). For example: -

-
-namespace gtk 
-{
-  using std::string;
-  using std::tr1::array;
-
-  class Window { ... };
-}
-
-

- In this example, std::string gets imported into - namespace gtk. The result is that use of - std::string inside namespace gtk can just use string, without the explicit qualification. - As an added bonus, - std::string does not get imported into - the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the - using-declarations can wrapped in macros that - are set based on autoconf-tests to either "" or i.e. using - std::string; (depending on whether the system has - libstdc++ in std:: or not). (ideas from - <llewelly@dbritsch.dsl.xmission.com>, Karl Nelson - <kenelson@ece.ucdavis.edu>) -

- -
-

Macros for libstdc++

- -

All pre-processor switches and configurations are all gathered - in the file c++config.h, which is generated during - the libstdc++ configuration and build process, and included by - files part of the public libstdc++ API. Most of these macros - should not be used by consumers of libstdc++, and are reserved - for internal implementation use. These macros cannot be - redefined. However, a select handful of these macro - control libstdc++ extensions and extra features, or provide - versioning information for the API, and are able to be used. -

- -

All library macros begin with _GLIBCXX_ (except for - versions 3.1.x to 3.3.x, which use _GLIBCPP_). -

- -

Below is the macro which users may check for library version - information.

- -
-
__GLIBCXX__
The current version of - libstdc++ in compressed ISO date format, form of an unsigned - long. For details on the value of this particular macro for a - particular release, please consult this - document.
- -

Below are the macros which users may change with #define/#undef or - with -D/-U compiler flags. 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 library build and configure time - (documented here), with the - various --enable/--disable choices being translated to - #define/#undef). -

- -

"ABI" means that changing from the default value may - mean changing the ABI of compiled code. In other words, these - choices control code which has already been compiled (i.e., in a - binary such as libstdc++.a/.so). If you explicitly #define or - #undef these macros, the headers may see different code - paths, but the libraries which you link against will not. - Experimenting with different values with the expectation of - consistent linkage requires changing the config headers before - building/installing the library. -

- -
-
_GLIBCXX_DEPRECATED
-
Defined by default. Not configurable. ABI-changing. Turning this off - removes older ARM-style iostreams code, and other anachronisms - from the API. This macro is dependent on the version of the - standard being tracked, and as a result may give different results for - -std=c++98 and -std=c++0x. This may - be useful in updating old C++ code which no longer meet the - requirements of the language, or for checking current code - against new language standards.
- -
_GLIBCXX_FORCE_NEW
Undefined by - default. When defined, memory allocation and allocators controlled - by libstdc++ call operator new/delete without caching and - pooling. Configurable via - --enable-libstdcxx-allocator. ABI-changing. -
- - -
_GLIBCXX_CONCEPT_CHECKS
Undefined by - default. Configurable via --enable-concept-checks. - When defined, performs compile-time checking on certain template - instantiations to detect violations of the requirements of the - standard. This is described in more detail here.
- -
_GLIBCXX_DEBUG
-
Undefined by default. When defined, compiles - user code using the libstdc++ debug - mode. -
-
_GLIBCXX_DEBUG_PEDANTIC
-
Undefined by default. When defined while - compiling with the libstdc++ debug - mode, makes the debug mode extremely picky by making the use - of libstdc++ extensions and libstdc++-specific behavior into - errors. -
-
_GLIBCXX_PARALLEL
-
Undefined by default. When defined, compiles - user code using the libstdc++ parallel - mode. -
-
- -
-

The Standard C++ library and multithreading

-

This section discusses issues surrounding the proper compilation - of multithreaded applications which use the Standard C++ - library. This information is GCC-specific since the C++ - standard does not address matters of multithreaded applications. - Unless explicitly prefaced, all information in this section is - relevant to the GCC 3.0 release and all later releases. -

-

Earlier GCC releases had a somewhat different approach to - threading configuration and proper compilation. Before GCC 3.0, - configuration of the threading model was dictated by compiler - command-line options and macros (both of which were somewhat - thread-implementation and port-specific). There were no - guarantees related to being able to link code compiled with one - set of options and macro setting with another set. For GCC 3.0, - configuration of the threading model used with libraries and - user-code is performed when GCC is configured and built using - the --enable-threads and --disable-threads options. The ABI is - stable for symbol name-mangling and limited functional - compatibility exists between code compiled under different - threading models. -

-

All normal disclaimers aside, multithreaded C++ application are - only supported when libstdc++ and all user code was built with - compilers which report (via gcc/g++ -v ) the same thread - model and that model is not single. As long as your - final application is actually single-threaded, then it should be - safe to mix user code built with a thread model of - single with a libstdc++ and other C++ libraries built - with another thread model useful on the platform. Other mixes - may or may not work but are not considered supported. (Thus, if - you distribute a shared C++ library in binary form only, it may - be best to compile it with a GCC configured with - --enable-threads for maximal interchangeability and usefulness - with a user population that may have built GCC with either - --enable-threads or --disable-threads.) -

-

When you link a multithreaded application, you will probably - need to add a library or flag to g++. This is a very - non-standardized area of GCC across ports. Some ports support a - special flag (the spelling isn't even standardized yet) to add - all required macros to a compilation (if any such flags are - required then you must provide the flag for all compilations not - just linking) and link-library additions and/or replacements at - link time. The documentation is weak. Here is a quick summary - to display how ad hoc this is: On Solaris, both -pthreads and - -threads (with subtly different meanings) are honored. On OSF, - -pthread and -threads (with subtly different meanings) are - honored. On Linux/i386, -pthread is honored. On FreeBSD, - -pthread is honored. Some other ports use other switches. - AFAIK, none of this is properly documented anywhere other than - in ``gcc -dumpspecs'' (look at lib and cpp entries). -

-

See FAQ (general overview), 23 (containers), and 27 (I/O) for more information. -

-

The libstdc++ library has been designed so that it can be used in - multithreaded applications (with libstdc++-v2 this was - only true of the STL parts.) The first problem is - finding a fast method of implementation portable to all - platforms. Due to historical reasons, some of the library is - written against per-CPU-architecture spinlocks and other parts - against the gthr.h abstraction layer which is provided by gcc. - A minor problem that pops up every so often is different - interpretations of what "thread-safe" means for a - library (not a general program). We currently use the same - definition that SGI uses for their STL subset. However, the - exception for read-only containers only applies to the STL - components. This definition is widely-used and something similar - will be used in the next version of the C++ standard library. -

-

Here is a small link farm to threads (no pun) in the mail archives - that discuss the threading problem. Each link is to the first - 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.
    • -
  • - This message inspired a recent updating of issues with threading - and the SGI STL library. It also contains some example - POSIX-multithreaded STL code.
    • -
-

(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.) -

-

This section will be updated as new and interesting issues come - to light. -

-

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

- -
-

Behavior specific to libstdc++

-

The ISO standard defines the following phrase: -

-
-
[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, - linker, runtime loader, and other elements of "the - implementation" are documented elsewhere. Everything listed in - Annex B, Implementation Qualities, are also part of the compiler, not - the library. -

-

For each entry, we give the section number of the standard, when - applicable. This list is probably incomplet and inkorrekt. -

-

[1.9]/11 #3 If isatty(3) is true, then - interactive stream support is implied. -

-

[17.4.4.5] Non-reentrant functions are probably best - discussed in the various sections on multithreading (see above). -

- -

[18.1]/4 The type of NULL is described - here. -

-

[18.3]/8 Even though it's listed in the library - sections, libstdc++ 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.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 - class. But they are the mangled names; you will need to call - c++filt and pass the names as command-line parameters to - demangle them, or call a - runtime demangler function. - (The classes in <stdexcept> have constructors which - require an argument to use later for what() calls, so the - problem of what()'s value does not arise in most - user-defined exceptions.) -

-

[18.5.1]/7 The return value of - std::type_info::name() is the mangled type name (see the - previous entry for more). -

-

[20.1.5]/5 "Implementors are encouraged to - supply libraries that can accept allocators that encapsulate more - general memory models and that support non-equal instances. In such - implementations, any requirements imposed on allocators by containers - beyond those requirements that appear in Table 32, and the semantics - of containers and algorithms when allocator instances compare - non-equal, are implementation-defined." As yet we don't - 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,
- others... - Nope, these types are called implementation-defined because you - shouldn't be taking advantage of their underlying types. Listing them - here would defeat the purpose. :-) -

-

[21.1.3.1]/5 I don't really know about the mbstate_t - stuff... see the chapter 22 notes - for what does exist. -

-

[22.*] Anything and everything we have on locale - implementation will be described - over here. -

-

[26.2.8]/9 I have no idea what - complex<T>'s pow(0,0) returns. -

-

[27.4.2.4]/2 Calling - std::ios_base::sync_with_stdio after I/O has already been - performed on the standard stream objects will - flush the buffers, and - destroy and recreate the underlying buffer instances. Whether or not - the previously-written I/O is destroyed in this process depends mostly - on the --enable-libio choice: for stdio, if the written data is - already in the stdio buffer, the data may be completely safe! -

-

[27.6.1.1.2],
- [27.6.2.3] The I/O sentry ctor and dtor can perform - additional work than the minimum required. We are not currently taking - advantage of this yet. -

-

[27.7.1.3]/16,
- [27.8.1.4]/10 - The effects of pubsetbuf/setbuf are described - in this chapter. -

-

[27.8.1.4]/16 Calling fstream::sync when - a get area exists will... whatever fflush() does, I think. -

-

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

- - -

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

- - - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - - - diff --git a/libstdc++-v3/doc/html/17_intro/license.html b/libstdc++-v3/doc/html/17_intro/license.html deleted file mode 100644 index 294a00892d32..000000000000 --- a/libstdc++-v3/doc/html/17_intro/license.html +++ /dev/null @@ -1,119 +0,0 @@ - - - - - - - - - - - libstdc++ copying - - - - - -

Licenses for the Library

- -

There are two licenses affecting GNU libstdc++: one for the code, and - one for the documentation. Here we will describe both of them, and try - to answer some of the widespread questions. If you have more questions, - ask the FSF or the - gcc mailing list; the person - writing this page is a programmer, not a lawyer. -

- -
- -

The Code: Runtime GPL

- -

The source code of libstdc++ is distributed under version 2 of the - 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
-   this file and link it with other files to produce an executable, this
-   file does not by itself cause the resulting executable to be covered by
-   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. -

- - -

Q: So any program which uses libstdc++ falls under the GPL? -
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 - 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 - are expanded inside the code that uses the library. So to allow people - to replace the library code, someone using the library would have to - distribute their own source, rendering the LGPL equivalent to the GPL. -

- -

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, - but we won't punish you or sue you if you choose otherwise. -

- -
- -

The Docs: GPL, FDL

- -

The documentation shipped with the library and made available over the - web, excluding the pages generated from source comments, are copyrighted - by the Free Software Foundation, and placed under - the GNU Free Documentation License version 1.1. - There are no Front-Cover Texts, no Back-Cover Texts, and - - no Invariant Sections. -

- -

For documentation generated by doxygen or other automated tools -via processing source code comments and markup, the original source -code license applies to the generated files. Thus, the doxygen -documents are licensed GPL. -

- -

If you plan on making copies of the documentation, please let us know. - We can probably offer suggestions. -

- - - - -
-

-Comments and suggestions about this page are welcome, and may be sent to -the libstdc++ mailing list. -Comments or questions about the licenses themselves are also welcome, and -should be directed to the GCC list as descibed above. -

- - - - - - diff --git a/libstdc++-v3/doc/html/17_intro/porting.html b/libstdc++-v3/doc/html/17_intro/porting.html deleted file mode 100644 index 2a561a9abc30..000000000000 --- a/libstdc++-v3/doc/html/17_intro/porting.html +++ /dev/null @@ -1,992 +0,0 @@ - - -Porting libstdc++ - - - - - - - - -

Porting libstdc++

-
-

-Node: Top, -Next: , -Up: (dir) -
-
- -

Porting libstdc++

- -

This document explains how to port libstdc++ (the GNU C++ library) to -a new target. - -

In order to make the GNU C++ library (libstdc++) work with a new -target, you must edit some configuration files and provide some new -header files. Unless this is done, libstdc++ will use generic -settings which may not be correct for your target; even if they are -correct, they will likely be inefficient. - -

Before you get started, make sure that you have a working C library on -your target. The C library need not precisely comply with any -particular standard, but should generally conform to the requirements -imposed by the ANSI/ISO standard. - -

In addition, you should try to verify that the C++ compiler generally -works. It is difficult to test the C++ compiler without a working -library, but you should at least try some minimal test cases. - -

(Note that what we think of as a "target," the library refers to as -a "host." The comment at the top of configure.ac explains why.) - -

Here are the primary steps required to port the library: - -

- -
-

-Node: Operating system, -Next: , -Previous: Top, -Up: Top -
-
- -

Operating system

- -

If you are porting to a new operating system (as opposed to a new chip -using an existing operating system), you will need to create a new -directory in the config/os hierarchy. For example, the IRIX -configuration files are all in config/os/irix. There is no set -way to organize the OS configuration directory. For example, -config/os/solaris/solaris-2.6 and -config/os/solaris/solaris-2.7 are used as configuration -directories for these two versions of Solaris. On the other hand, both -Solaris 2.7 and Solaris 2.8 use the config/os/solaris/solaris-2.7 -directory. The important information is that there needs to be a -directory under config/os to store the files for your operating -system. - -

You might have to change the configure.host file to ensure that -your new directory is activated. Look for the switch statement that sets -os_include_dir, and add a pattern to handle your operating system -if the default will not suffice. The switch statement switches on only -the OS portion of the standard target triplet; e.g., the solaris2.8 -in sparc-sun-solaris2.8. If the new directory is named after the -OS portion of the triplet (the default), then nothing needs to be changed. - -

The first file to create in this directory, should be called -os_defines.h. This file contains basic macro definitions -that are required to allow the C++ library to work with your C library. - -

Several libstdc++ source files unconditionally define the macro -_POSIX_SOURCE. On many systems, defining this macro causes -large portions of the C library header files to be eliminated -at preprocessing time. Therefore, you may have to #undef this -macro, or define other macros (like _LARGEFILE_SOURCE or -__EXTENSIONS__). You won't know what macros to define or -undefine at this point; you'll have to try compiling the library and -seeing what goes wrong. If you see errors about calling functions -that have not been declared, look in your C library headers to see if -the functions are declared there, and then figure out what macros you -need to define. You will need to add them to the -CPLUSPLUS_CPP_SPEC macro in the GCC configuration file for your -target. It will not work to simply define these macros in -os_defines.h. - -

At this time, there are a few libstdc++-specific macros which may be -defined: - -

_GLIBCXX_USE_C99_CHECK may be defined to 1 to check C99 -function declarations (which are not covered by specialization below) -found in system headers against versions found in the library headers -derived from the standard. - -

_GLIBCXX_USE_C99_DYNAMIC may be defined to an expression that -yields 0 if and only if the system headers are exposing proper support -for C99 functions (which are not covered by specialization below). If -defined, it must be 0 while bootstrapping the compiler/rebuilding the -library. - -

_GLIBCXX_USE_C99_LONG_LONG_CHECK may be defined to 1 to check -the set of C99 long long function declarations found in system headers -against versions found in the library headers derived from the -standard. - -

_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC may be defined to an -expression that yields 0 if and only if the system headers are -exposing proper support for the set of C99 long long functions. If -defined, it must be 0 while bootstrapping the compiler/rebuilding the -library. - -

_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC may be defined to an -expression that yields 0 if and only if the system headers -are exposing proper support for the related set of macros. If defined, -it must be 0 while bootstrapping the compiler/rebuilding the library. - -

_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK may be defined -to 1 to check the related set of function declarations found in system -headers against versions found in the library headers derived from -the standard. - -

_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC may be defined -to an expression that yields 0 if and only if the system headers -are exposing proper support for the related set of functions. If defined, -it must be 0 while bootstrapping the compiler/rebuilding the library. - -

Finally, you should bracket the entire file in an include-guard, like -this: - -

     #ifndef _GLIBCXX_OS_DEFINES
-     #define _GLIBCXX_OS_DEFINES
-     ...
-     #endif
-
- -

We recommend copying an existing os_defines.h to use as a -starting point. - -

-

-Node: CPU, -Next: , -Previous: Operating system, -Up: Top -
-
- -

CPU

- -

If you are porting to a new chip (as opposed to a new operating system -running on an existing chip), you will need to create a new directory in the -config/cpu hierarchy. Much like the Operating system setup, -there are no strict rules on how to organize the CPU configuration -directory, but careful naming choices will allow the configury to find your -setup files without explicit help. - -

We recommend that for a target triplet <CPU>-<vendor>-<OS>, you -name your configuration directory config/cpu/<CPU>. If you do this, -the configury will find the directory by itself. Otherwise you will need to -edit the configure.host file and, in the switch statement that sets -cpu_include_dir, add a pattern to handle your chip. - -

Note that some chip families share a single configuration directory, for -example, alpha, alphaev5, and alphaev6 all use the -config/cpu/alpha directory, and there is an entry in the -configure.host switch statement to handle this. - -

The cpu_include_dir sets default locations for the files controlling -Thread safety and Numeric limits, if the defaults are not -appropriate for your chip. - -

-

-Node: Character types, -Next: , -Previous: CPU, -Up: Top -
-
- -

Character types

- -

The library requires that you provide three header files to implement -character classification, analogous to that provided by the C libraries -<ctype.h> header. You can model these on the files provided in -config/os/generic. However, these files will almost -certainly need some modification. - -

The first file to write is ctype_base.h. This file provides -some very basic information about character classification. The libstdc++ -library assumes that your C library implements <ctype.h> by using -a table (indexed by character code) containing integers, where each of -these integers is a bit-mask indicating whether the character is -upper-case, lower-case, alphabetic, etc. The ctype_base.h -file gives the type of the integer, and the values of the various bit -masks. You will have to peer at your own <ctype.h> to figure out -how to define the values required by this file. - -

The ctype_base.h header file does not need include guards. -It should contain a single struct definition called -ctype_base. This struct should contain two type -declarations, and one enumeration declaration, like this example, taken -from the IRIX configuration: - -

     struct ctype_base
-     {
-       typedef unsigned int 	mask;
-       typedef int* 		__to_type;
-     
-       enum
-       {
-         space = _ISspace,
-         print = _ISprint,
-         cntrl = _IScntrl,
-         upper = _ISupper,
-         lower = _ISlower,
-         alpha = _ISalpha,
-         digit = _ISdigit,
-         punct = _ISpunct,
-         xdigit = _ISxdigit,
-         alnum = _ISalnum,
-         graph = _ISgraph
-       };
-     };
-
- -

The mask type is the type of the elements in the table. If your -C library uses a table to map lower-case numbers to upper-case numbers, -and vice versa, you should define __to_type to be the type of the -elements in that table. If you don't mind taking a minor performance -penalty, or if your library doesn't implement toupper and -tolower in this way, you can pick any pointer-to-integer type, -but you must still define the type. - -

The enumeration should give definitions for all the values in the above -example, using the values from your native <ctype.h>. They can -be given symbolically (as above), or numerically, if you prefer. You do -not have to include <ctype.h> in this header; it will always be -included before ctype_base.h is included. - -

The next file to write is ctype_noninline.h, which also does -not require include guards. This file defines a few member functions -that will be included in include/bits/locale_facets.h. The first -function that must be written is the ctype<char>::ctype -constructor. Here is the IRIX example: - -

     ctype<char>::ctype(const mask* __table = 0, bool __del = false,
-           size_t __refs = 0)
-       : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
-         _M_toupper(NULL),
-         _M_tolower(NULL),
-         _M_ctable(NULL),
-         _M_table(!__table
-                  ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
-                  : __table)
-       { }
-
- -

There are two parts of this that you might choose to alter. The first, -and most important, is the line involving __libc_attr. That is -IRIX system-dependent code that gets the base of the table mapping -character codes to attributes. You need to substitute code that obtains -the address of this table on your system. If you want to use your -operating system's tables to map upper-case letters to lower-case, and -vice versa, you should initialize _M_toupper and -_M_tolower with those tables, in similar fashion. - -

Now, you have to write two functions to convert from upper-case to -lower-case, and vice versa. Here are the IRIX versions: - -

     char
-     ctype<char>::do_toupper(char __c) const
-     { return _toupper(__c); }
-     
-     char
-     ctype<char>::do_tolower(char __c) const
-     { return _tolower(__c); }
-
- -

Your C library provides equivalents to IRIX's _toupper and -_tolower. If you initialized _M_toupper and -_M_tolower above, then you could use those tables instead. - -

Finally, you have to provide two utility functions that convert strings -of characters. The versions provided here will always work - but you -could use specialized routines for greater performance if you have -machinery to do that on your system: - -

     const char*
-     ctype<char>::do_toupper(char* __low, const char* __high) const
-     {
-       while (__low < __high)
-         {
-           *__low = do_toupper(*__low);
-           ++__low;
-         }
-       return __high;
-     }
-     
-     const char*
-     ctype<char>::do_tolower(char* __low, const char* __high) const
-     {
-       while (__low < __high)
-         {
-           *__low = do_tolower(*__low);
-           ++__low;
-         }
-       return __high;
-     }
-
- -

You must also provide the ctype_inline.h file, which -contains a few more functions. On most systems, you can just copy -config/os/generic/ctype_inline.h and use it on your system. - -

In detail, the functions provided test characters for particular -properties; they are analogous to the functions like isalpha and -islower provided by the C library. - -

The first function is implemented like this on IRIX: - -

     bool
-     ctype<char>::
-     is(mask __m, char __c) const throw()
-     { return (_M_table)[(unsigned char)(__c)] & __m; }
-
- -

The _M_table is the table passed in above, in the constructor. -This is the table that contains the bitmasks for each character. The -implementation here should work on all systems. - -

The next function is: - -

     const char*
-     ctype<char>::
-     is(const char* __low, const char* __high, mask* __vec) const throw()
-     {
-       while (__low < __high)
-         *__vec++ = (_M_table)[(unsigned char)(*__low++)];
-       return __high;
-     }
-
- -

This function is similar; it copies the masks for all the characters -from __low up until __high into the vector given by -__vec. - -

The last two functions again are entirely generic: - -

     const char*
-     ctype<char>::
-     scan_is(mask __m, const char* __low, const char* __high) const throw()
-     {
-       while (__low < __high && !this->is(__m, *__low))
-         ++__low;
-       return __low;
-     }
-     
-     const char*
-     ctype<char>::
-     scan_not(mask __m, const char* __low, const char* __high) const throw()
-     {
-       while (__low < __high && this->is(__m, *__low))
-         ++__low;
-       return __low;
-     }
-
- -
-

-Node: Thread safety, -Next: , -Previous: Character types, -Up: Top -
-
- -

Thread safety

- -

The C++ library string functionality requires a couple of atomic -operations to provide thread-safety. If you don't take any special -action, the library will use stub versions of these functions that are -not thread-safe. They will work fine, unless your applications are -multi-threaded. - -

If you want to provide custom, safe, versions of these functions, there -are two distinct approaches. One is to provide a version for your CPU, -using assembly language constructs. The other is to use the -thread-safety primitives in your operating system. In either case, you -make a file called atomicity.h, and the variable -ATOMICITYH must point to this file. - -

If you are using the assembly-language approach, put this code in -config/cpu/<chip>/atomicity.h, where chip is the name of -your processor (see CPU). No additional changes are necessary to -locate the file in this case; ATOMICITYH will be set by default. - -

If you are using the operating system thread-safety primitives approach, -you can also put this code in the same CPU directory, in which case no more -work is needed to locate the file. For examples of this approach, -see the atomicity.h file for IRIX or IA64. - -

Alternatively, if the primitives are more closely related to the OS -than they are to the CPU, you can put the atomicity.h file in -the Operating system directory instead. In this case, you must -edit configure.host, and in the switch statement that handles -operating systems, override the ATOMICITYH variable to point to -the appropriate os_include_dir. For examples of this approach, -see the atomicity.h file for AIX. - -

With those bits out of the way, you have to actually write -atomicity.h itself. This file should be wrapped in an -include guard named _GLIBCXX_ATOMICITY_H. It should define one -type, and two functions. - -

The type is _Atomic_word. Here is the version used on IRIX: - -

     typedef long _Atomic_word;
-
- -

This type must be a signed integral type supporting atomic operations. -If you're using the OS approach, use the same type used by your system's -primitives. Otherwise, use the type for which your CPU provides atomic -primitives. - -

Then, you must provide two functions. The bodies of these functions -must be equivalent to those provided here, but using atomic operations: - -

     static inline _Atomic_word
-     __attribute__ ((__unused__))
-     __exchange_and_add (_Atomic_word* __mem, int __val)
-     {
-       _Atomic_word __result = *__mem;
-       *__mem += __val;
-       return __result;
-     }
-     
-     static inline void
-     __attribute__ ((__unused__))
-     __atomic_add (_Atomic_word* __mem, int __val)
-     {
-       *__mem += __val;
-     }
-
- -
-

-Node: Numeric limits, -Next: , -Previous: Thread safety, -Up: Top -
-
- -

Numeric limits

- -

The C++ library requires information about the fundamental data types, -such as the minimum and maximum representable values of each type. -You can define each of these values individually, but it is usually -easiest just to indicate how many bits are used in each of the data -types and let the library do the rest. For information about the -macros to define, see the top of include/bits/std_limits.h. - -

If you need to define any macros, you can do so in os_defines.h. -However, if all operating systems for your CPU are likely to use the -same values, you can provide a CPU-specific file instead so that you -do not have to provide the same definitions for each operating system. -To take that approach, create a new file called cpu_limits.h in -your CPU configuration directory (see CPU). - -

-

-Node: Libtool, -Next: , -Previous: Numeric limits, -Up: Top -
-
- -

Libtool

- -

The C++ library is compiled, archived and linked with libtool. -Explaining the full workings of libtool is beyond the scope of this -document, but there are a few, particular bits that are necessary for -porting. - -

Some parts of the libstdc++ library are compiled with the libtool ---tags CXX option (the C++ definitions for libtool). Therefore, -ltcf-cxx.sh in the top-level directory needs to have the correct -logic to compile and archive objects equivalent to the C version of libtool, -ltcf-c.sh. Some libtool targets have definitions for C but not -for C++, or C++ definitions which have not been kept up to date. - -

The C++ run-time library contains initialization code that needs to be -run as the library is loaded. Often, that requires linking in special -object files when the C++ library is built as a shared library, or -taking other system-specific actions. - -

The libstdc++ library is linked with the C version of libtool, even -though it is a C++ library. Therefore, the C version of libtool needs to -ensure that the run-time library initializers are run. The usual way to -do this is to build the library using gcc -shared. - -

If you need to change how the library is linked, look at -ltcf-c.sh in the top-level directory. Find the switch statement -that sets archive_cmds. Here, adjust the setting for your -operating system. - -

-

-Node: GNU Free Documentation License, -Previous: Libtool, -Up: Top -
-
- -

GNU Free Documentation License

- -
Version 1.2, November 2002
-
     Copyright © 2000,2001,2002 Free Software Foundation, Inc.
-     51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
-     
-     Everyone is permitted to copy and distribute verbatim copies
-     of this license document, but changing it is not allowed.
-
- -
    -
  1. PREAMBLE - -

    The purpose of this License is to make a manual, textbook, or other -functional and useful document free in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -

    This License is a kind of "copyleft", which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -

    We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -

  2. APPLICABILITY AND DEFINITIONS - -

    This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The "Document", below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as "you". You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -

    A "Modified Version" of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -

    A "Secondary Section" is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -

    The "Invariant Sections" are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -

    The "Cover Texts" are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -

    A "Transparent" copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not "Transparent" is called "Opaque". - -

    Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input -format, SGML or XML using a publicly available -DTD, and standard-conforming simple HTML, -PostScript or PDF designed for human modification. Examples -of transparent image formats include PNG, XCF and -JPG. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, SGML or -XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML, -PostScript or PDF produced by some word processors for -output purposes only. - -

    The "Title Page" means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, "Title Page" means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -

    A section "Entitled XYZ" means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as "Acknowledgements", -"Dedications", "Endorsements", or "History".) To "Preserve the Title" -of such a section when you modify the Document means that it remains a -section "Entitled XYZ" according to this definition. - -

    The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -

  3. VERBATIM COPYING - -

    You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -

    You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -

  4. COPYING IN QUANTITY - -

    If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -

    If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -

    If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -

    It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -

  5. MODIFICATIONS - -

    You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -

      -
    1. Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -
    2. List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -
    3. State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -
    4. Preserve all the copyright notices of the Document. - -
    5. Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -
    6. Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -
    7. Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -
    8. Include an unaltered copy of this License. - -
    9. Preserve the section Entitled "History", Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled "History" in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -
    10. Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the "History" section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -
    11. For any section Entitled "Acknowledgements" or "Dedications", Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -
    12. Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -
    13. Delete any section Entitled "Endorsements". Such a section -may not be included in the Modified Version. - -
    14. Do not retitle any existing section to be Entitled "Endorsements" or -to conflict in title with any Invariant Section. - -
    15. Preserve any Warranty Disclaimers. -
    - -

    If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -

    You may add a section Entitled "Endorsements", provided it contains -nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -

    You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -

    The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -

  6. COMBINING DOCUMENTS - -

    You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -

    The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -

    In the combination, you must combine any sections Entitled "History" -in the various original documents, forming one section Entitled -"History"; likewise combine any sections Entitled "Acknowledgements", -and any sections Entitled "Dedications". You must delete all -sections Entitled "Endorsements." - -

  7. COLLECTIONS OF DOCUMENTS - -

    You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -

    You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -

  8. AGGREGATION WITH INDEPENDENT WORKS - -

    A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an "aggregate" if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -

    If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -

  9. TRANSLATION - -

    Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warrany Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -

    If a section in the Document is Entitled "Acknowledgements", -"Dedications", or "History", the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -

  10. TERMINATION - -

    You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - -

  11. FUTURE REVISIONS OF THIS LICENSE - -

    The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. - -

    Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License "or any later version" applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. -

- -

ADDENDUM: How to use this License for your documents

- -

To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -

       Copyright (C)  year  your name.
-       Permission is granted to copy, distribute and/or modify this document
-       under the terms of the GNU Free Documentation License, Version 1.2
-       or any later version published by the Free Software Foundation;
-       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-       A copy of the license is included in the section entitled ``GNU
-       Free Documentation License''.
-
- -

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the "with...Texts." line with this: - -

         with the Invariant Sections being list their titles, with
-         the Front-Cover Texts being list, and with the Back-Cover Texts
-         being list.
-
- -

If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -

If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -

-

Table of Contents

- -
- - - diff --git a/libstdc++-v3/doc/html/17_intro/porting.texi b/libstdc++-v3/doc/html/17_intro/porting.texi deleted file mode 100644 index 090bdf771556..000000000000 --- a/libstdc++-v3/doc/html/17_intro/porting.texi +++ /dev/null @@ -1,570 +0,0 @@ -\input texinfo - -@c --------------------------------------------------------------------- -@c Prologue -@c --------------------------------------------------------------------- - -@setfilename porting.info -@settitle Porting libstdc++-v3 -@setchapternewpage odd - -@copying -Copyright @copyright{} 2000, 2001, 2002, 2003, 2005 -Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License'', the Front-Cover -texts being (a) (see below), and with the Back-Cover Texts being (b) -(see below). A copy of the license is included in the section entitled -``GNU Free Documentation License''. - -(a) The FSF's Front-Cover Text is: - - A GNU Manual - -(b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU - software. Copies published by the Free Software Foundation raise - funds for GNU development. -@end copying - -@ifinfo -This file explains how to port libstdc++-v3 (the GNU C++ library) to -a new target. - -@insertcopying -@end ifinfo - -@c --------------------------------------------------------------------- -@c Titlepage -@c --------------------------------------------------------------------- - -@titlepage -@title Porting libstdc++-v3 -@author Mark Mitchell -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@c --------------------------------------------------------------------- -@c Top -@c --------------------------------------------------------------------- - -@node Top -@top Porting libstdc++-v3 - -This document explains how to port libstdc++-v3 (the GNU C++ library) to -a new target. - -In order to make the GNU C++ library (libstdc++-v3) work with a new -target, you must edit some configuration files and provide some new -header files. Unless this is done, libstdc++-v3 will use generic -settings which may not be correct for your target; even if they are -correct, they will likely be inefficient. - -Before you get started, make sure that you have a working C library on -your target. The C library need not precisely comply with any -particular standard, but should generally conform to the requirements -imposed by the ANSI/ISO standard. - -In addition, you should try to verify that the C++ compiler generally -works. It is difficult to test the C++ compiler without a working -library, but you should at least try some minimal test cases. - -(Note that what we think of as a ``target,'' the library refers to as -a ``host.'' The comment at the top of @file{configure.ac} explains why.) - -Here are the primary steps required to port the library: - -@menu -* Operating system:: Configuring for your operating system. -* CPU:: Configuring for your processor chip. -* Character types:: Implementing character classification. -* Thread safety:: Implementing atomic operations. -* Numeric limits:: Implementing numeric limits. -* Libtool:: Using libtool. -* GNU Free Documentation License:: How you can copy and share this manual. -@end menu - -@c --------------------------------------------------------------------- -@c Operating system -@c --------------------------------------------------------------------- - -@node Operating system -@chapter Operating system - -If you are porting to a new operating system (as opposed to a new chip -using an existing operating system), you will need to create a new -directory in the @file{config/os} hierarchy. For example, the IRIX -configuration files are all in @file{config/os/irix}. There is no set -way to organize the OS configuration directory. For example, -@file{config/os/solaris/solaris-2.6} and -@file{config/os/solaris/solaris-2.7} are used as configuration -directories for these two versions of Solaris. On the other hand, both -Solaris 2.7 and Solaris 2.8 use the @file{config/os/solaris/solaris-2.7} -directory. The important information is that there needs to be a -directory under @file{config/os} to store the files for your operating -system. - -You might have to change the @file{configure.host} file to ensure that -your new directory is activated. Look for the switch statement that sets -@code{os_include_dir}, and add a pattern to handle your operating system -if the default will not suffice. The switch statement switches on only -the OS portion of the standard target triplet; e.g., the @code{solaris2.8} -in @code{sparc-sun-solaris2.8}. If the new directory is named after the -OS portion of the triplet (the default), then nothing needs to be changed. - -The first file to create in this directory, should be called -@file{os_defines.h}. This file contains basic macro definitions -that are required to allow the C++ library to work with your C library. - -Several libstdc++-v3 source files unconditionally define the macro -@code{_POSIX_SOURCE}. On many systems, defining this macro causes -large portions of the C library header files to be eliminated -at preprocessing time. Therefore, you may have to @code{#undef} this -macro, or define other macros (like @code{_LARGEFILE_SOURCE} or -@code{__EXTENSIONS__}). You won't know what macros to define or -undefine at this point; you'll have to try compiling the library and -seeing what goes wrong. If you see errors about calling functions -that have not been declared, look in your C library headers to see if -the functions are declared there, and then figure out what macros you -need to define. You will need to add them to the -@code{CPLUSPLUS_CPP_SPEC} macro in the GCC configuration file for your -target. It will not work to simply define these macros in -@file{os_defines.h}. - -At this time, there are a few libstdc++-v3-specific macros which may be -defined: - -@code{_GLIBCXX_USE_C99_CHECK} may be defined to 1 to check C99 -function declarations (which are not covered by specialization below) -found in system headers against versions found in the library headers -derived from the standard. - -@code{_GLIBCXX_USE_C99_DYNAMIC} may be defined to an expression that -yields 0 if and only if the system headers are exposing proper support -for C99 functions (which are not covered by specialization below). If -defined, it must be 0 while bootstrapping the compiler/rebuilding the -library. - -@code{_GLIBCXX_USE_C99_LONG_LONG_CHECK} may be defined to 1 to check -the set of C99 long long function declarations found in system headers -against versions found in the library headers derived from the -standard. - -@code{_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC} may be defined to an -expression that yields 0 if and only if the system headers are -exposing proper support for the set of C99 long long functions. If -defined, it must be 0 while bootstrapping the compiler/rebuilding the -library. - -@code{_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC} may be defined to an -expression that yields 0 if and only if the system headers -are exposing proper support for the related set of macros. If defined, -it must be 0 while bootstrapping the compiler/rebuilding the library. - -@code{_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK} may be defined -to 1 to check the related set of function declarations found in system -headers against versions found in the library headers derived from -the standard. - -@code{_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC} may be defined -to an expression that yields 0 if and only if the system headers -are exposing proper support for the related set of functions. If defined, -it must be 0 while bootstrapping the compiler/rebuilding the library. - -Finally, you should bracket the entire file in an include-guard, like -this: - -@example -#ifndef _GLIBCXX_OS_DEFINES -#define _GLIBCXX_OS_DEFINES -... -#endif -@end example - -We recommend copying an existing @file{os_defines.h} to use as a -starting point. - -@c --------------------------------------------------------------------- -@c CPU -@c --------------------------------------------------------------------- - -@node CPU -@chapter CPU - -If you are porting to a new chip (as opposed to a new operating system -running on an existing chip), you will need to create a new directory in the -@file{config/cpu} hierarchy. Much like the @ref{Operating system} setup, -there are no strict rules on how to organize the CPU configuration -directory, but careful naming choices will allow the configury to find your -setup files without explicit help. - -We recommend that for a target triplet @code{--}, you -name your configuration directory @file{config/cpu/}. If you do this, -the configury will find the directory by itself. Otherwise you will need to -edit the @file{configure.host} file and, in the switch statement that sets -@code{cpu_include_dir}, add a pattern to handle your chip. - -Note that some chip families share a single configuration directory, for -example, @code{alpha}, @code{alphaev5}, and @code{alphaev6} all use the -@file{config/cpu/alpha} directory, and there is an entry in the -@file{configure.host} switch statement to handle this. - -The @code{cpu_include_dir} sets default locations for the files controlling -@ref{Thread safety} and @ref{Numeric limits}, if the defaults are not -appropriate for your chip. - - -@c --------------------------------------------------------------------- -@c Character types -@c --------------------------------------------------------------------- - -@node Character types -@chapter Character types - -The library requires that you provide three header files to implement -character classification, analogous to that provided by the C libraries -@file{} header. You can model these on the files provided in -@file{config/os/generic}. However, these files will almost -certainly need some modification. - -The first file to write is @file{ctype_base.h}. This file provides -some very basic information about character classification. The libstdc++-v3 -library assumes that your C library implements @file{} by using -a table (indexed by character code) containing integers, where each of -these integers is a bit-mask indicating whether the character is -upper-case, lower-case, alphabetic, etc. The @file{ctype_base.h} -file gives the type of the integer, and the values of the various bit -masks. You will have to peer at your own @file{} to figure out -how to define the values required by this file. - -The @file{ctype_base.h} header file does not need include guards. -It should contain a single @code{struct} definition called -@code{ctype_base}. This @code{struct} should contain two type -declarations, and one enumeration declaration, like this example, taken -from the IRIX configuration: - -@example -struct ctype_base -@{ - typedef unsigned int mask; - typedef int* __to_type; - - enum - @{ - space = _ISspace, - print = _ISprint, - cntrl = _IScntrl, - upper = _ISupper, - lower = _ISlower, - alpha = _ISalpha, - digit = _ISdigit, - punct = _ISpunct, - xdigit = _ISxdigit, - alnum = _ISalnum, - graph = _ISgraph - @}; -@}; -@end example - -@noindent -The @code{mask} type is the type of the elements in the table. If your -C library uses a table to map lower-case numbers to upper-case numbers, -and vice versa, you should define @code{__to_type} to be the type of the -elements in that table. If you don't mind taking a minor performance -penalty, or if your library doesn't implement @code{toupper} and -@code{tolower} in this way, you can pick any pointer-to-integer type, -but you must still define the type. - -The enumeration should give definitions for all the values in the above -example, using the values from your native @file{}. They can -be given symbolically (as above), or numerically, if you prefer. You do -not have to include @file{} in this header; it will always be -included before @file{ctype_base.h} is included. - -The next file to write is @file{ctype_noninline.h}, which also does -not require include guards. This file defines a few member functions -that will be included in @file{include/bits/locale_facets.h}. The first -function that must be written is the @code{ctype::ctype} -constructor. Here is the IRIX example: - -@example -ctype::ctype(const mask* __table = 0, bool __del = false, - size_t __refs = 0) - : _Ctype_nois(__refs), _M_del(__table != 0 && __del), - _M_toupper(NULL), - _M_tolower(NULL), - _M_ctable(NULL), - _M_table(!__table - ? (const mask*) (__libc_attr._ctype_tbl->_class + 1) - : __table) - @{ @} -@end example - -@noindent -There are two parts of this that you might choose to alter. The first, -and most important, is the line involving @code{__libc_attr}. That is -IRIX system-dependent code that gets the base of the table mapping -character codes to attributes. You need to substitute code that obtains -the address of this table on your system. If you want to use your -operating system's tables to map upper-case letters to lower-case, and -vice versa, you should initialize @code{_M_toupper} and -@code{_M_tolower} with those tables, in similar fashion. - -Now, you have to write two functions to convert from upper-case to -lower-case, and vice versa. Here are the IRIX versions: - -@example -char -ctype::do_toupper(char __c) const -@{ return _toupper(__c); @} - -char -ctype::do_tolower(char __c) const -@{ return _tolower(__c); @} -@end example - -@noindent -Your C library provides equivalents to IRIX's @code{_toupper} and -@code{_tolower}. If you initialized @code{_M_toupper} and -@code{_M_tolower} above, then you could use those tables instead. - -Finally, you have to provide two utility functions that convert strings -of characters. The versions provided here will always work -- but you -could use specialized routines for greater performance if you have -machinery to do that on your system: - -@example -const char* -ctype::do_toupper(char* __low, const char* __high) const -@{ - while (__low < __high) - @{ - *__low = do_toupper(*__low); - ++__low; - @} - return __high; -@} - -const char* -ctype::do_tolower(char* __low, const char* __high) const -@{ - while (__low < __high) - @{ - *__low = do_tolower(*__low); - ++__low; - @} - return __high; -@} -@end example - -You must also provide the @file{ctype_inline.h} file, which -contains a few more functions. On most systems, you can just copy -@file{config/os/generic/ctype_inline.h} and use it on your system. - -In detail, the functions provided test characters for particular -properties; they are analogous to the functions like @code{isalpha} and -@code{islower} provided by the C library. - -The first function is implemented like this on IRIX: - -@example -bool -ctype:: -is(mask __m, char __c) const throw() -@{ return (_M_table)[(unsigned char)(__c)] & __m; @} -@end example - -@noindent -The @code{_M_table} is the table passed in above, in the constructor. -This is the table that contains the bitmasks for each character. The -implementation here should work on all systems. - -The next function is: - -@example -const char* -ctype:: -is(const char* __low, const char* __high, mask* __vec) const throw() -@{ - while (__low < __high) - *__vec++ = (_M_table)[(unsigned char)(*__low++)]; - return __high; -@} -@end example - -@noindent -This function is similar; it copies the masks for all the characters -from @code{__low} up until @code{__high} into the vector given by -@code{__vec}. - -The last two functions again are entirely generic: - -@example -const char* -ctype:: -scan_is(mask __m, const char* __low, const char* __high) const throw() -@{ - while (__low < __high && !this->is(__m, *__low)) - ++__low; - return __low; -@} - -const char* -ctype:: -scan_not(mask __m, const char* __low, const char* __high) const throw() -@{ - while (__low < __high && this->is(__m, *__low)) - ++__low; - return __low; -@} -@end example - -@c --------------------------------------------------------------------- -@c Thread safety -@c --------------------------------------------------------------------- - -@node Thread safety -@chapter Thread safety - -The C++ library string functionality requires a couple of atomic -operations to provide thread-safety. If you don't take any special -action, the library will use stub versions of these functions that are -not thread-safe. They will work fine, unless your applications are -multi-threaded. - -If you want to provide custom, safe, versions of these functions, there -are two distinct approaches. One is to provide a version for your CPU, -using assembly language constructs. The other is to use the -thread-safety primitives in your operating system. In either case, you -make a file called @file{atomicity.h}, and the variable -@code{ATOMICITYH} must point to this file. - -If you are using the assembly-language approach, put this code in -@file{config/cpu//atomicity.h}, where chip is the name of -your processor (@pxref{CPU}). No additional changes are necessary to -locate the file in this case; @code{ATOMICITYH} will be set by default. - -If you are using the operating system thread-safety primitives approach, -you can also put this code in the same CPU directory, in which case no more -work is needed to locate the file. For examples of this approach, -see the @file{atomicity.h} file for IRIX or IA64. - -Alternatively, if the primitives are more closely related to the OS -than they are to the CPU, you can put the @file{atomicity.h} file in -the @ref{Operating system} directory instead. In this case, you must -edit @file{configure.host}, and in the switch statement that handles -operating systems, override the @code{ATOMICITYH} variable to point to -the appropriate @code{os_include_dir}. For examples of this approach, -see the @file{atomicity.h} file for AIX. - -With those bits out of the way, you have to actually write -@file{atomicity.h} itself. This file should be wrapped in an -include guard named @code{_GLIBCXX_ATOMICITY_H}. It should define one -type, and two functions. - -The type is @code{_Atomic_word}. Here is the version used on IRIX: - -@example -typedef long _Atomic_word; -@end example - -@noindent -This type must be a signed integral type supporting atomic operations. -If you're using the OS approach, use the same type used by your system's -primitives. Otherwise, use the type for which your CPU provides atomic -primitives. - -Then, you must provide two functions. The bodies of these functions -must be equivalent to those provided here, but using atomic operations: - -@example -static inline _Atomic_word -__attribute__ ((__unused__)) -__exchange_and_add (_Atomic_word* __mem, int __val) -@{ - _Atomic_word __result = *__mem; - *__mem += __val; - return __result; -@} - -static inline void -__attribute__ ((__unused__)) -__atomic_add (_Atomic_word* __mem, int __val) -@{ - *__mem += __val; -@} -@end example - -@c --------------------------------------------------------------------- -@c Numeric limits -@c --------------------------------------------------------------------- - -@node Numeric limits -@chapter Numeric limits - -The C++ library requires information about the fundamental data types, -such as the minimum and maximum representable values of each type. -You can define each of these values individually, but it is usually -easiest just to indicate how many bits are used in each of the data -types and let the library do the rest. For information about the -macros to define, see the top of @file{include/bits/std_limits.h}. - -If you need to define any macros, you can do so in @file{os_defines.h}. -However, if all operating systems for your CPU are likely to use the -same values, you can provide a CPU-specific file instead so that you -do not have to provide the same definitions for each operating system. -To take that approach, create a new file called @file{cpu_limits.h} in -your CPU configuration directory (@pxref{CPU}). - -@c --------------------------------------------------------------------- -@c Libtool -@c --------------------------------------------------------------------- - -@node Libtool -@chapter Libtool - -The C++ library is compiled, archived and linked with libtool. -Explaining the full workings of libtool is beyond the scope of this -document, but there are a few, particular bits that are necessary for -porting. - -Some parts of the libstdc++-v3 library are compiled with the libtool -@code{--tags CXX} option (the C++ definitions for libtool). Therefore, -@file{ltcf-cxx.sh} in the top-level directory needs to have the correct -logic to compile and archive objects equivalent to the C version of libtool, -@file{ltcf-c.sh}. Some libtool targets have definitions for C but not -for C++, or C++ definitions which have not been kept up to date. - -The C++ run-time library contains initialization code that needs to be -run as the library is loaded. Often, that requires linking in special -object files when the C++ library is built as a shared library, or -taking other system-specific actions. - -The libstdc++-v3 library is linked with the C version of libtool, even -though it is a C++ library. Therefore, the C version of libtool needs to -ensure that the run-time library initializers are run. The usual way to -do this is to build the library using @code{gcc -shared}. - -If you need to change how the library is linked, look at -@file{ltcf-c.sh} in the top-level directory. Find the switch statement -that sets @code{archive_cmds}. Here, adjust the setting for your -operating system. - -@c --------------------------------------------------------------------- -@c GFDL -@c --------------------------------------------------------------------- - -@include fdl.texi - -@c --------------------------------------------------------------------- -@c Epilogue -@c --------------------------------------------------------------------- - -@contents -@bye diff --git a/libstdc++-v3/doc/html/17_intro/tr1_status.html b/libstdc++-v3/doc/html/17_intro/tr1_status.html deleted file mode 100644 index 3d3d673cf89c..000000000000 --- a/libstdc++-v3/doc/html/17_intro/tr1_status.html +++ /dev/null @@ -1,2322 +0,0 @@ - - - - - - - - - - - - Status of TR1 features in GCC - - GNU Project - Free Software Foundation (FSF) - - - - - - -

- Status of TR1 features in GCC -

- -

-This table is based on the table of contents of ISO/IEC DTR 19768 -Doc No: N1836=05-0096 Date: 2005-06-24 -Draft Technical Report on C++ Library Extensions -

- -

-In this implementation the header names are prefixed by -tr1/, for instance <tr1/functional>, -<tr1/memory>, and so on. -

- -

-This page describes the TR1 support in mainline GCC SVN, not in any particular -release. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SectionDescriptionDoneBrokenMissingComments
2General Utilities
2.1Reference wrappersdone
2.1.1Additions to header <functional> synopsisdone
2.1.2Class template reference_wrapperdone
2.1.2.1reference_wrapper construct/copy/destroydone
2.1.2.2reference_wrapper assignmentdone
2.1.2.3reference_wrapper accessdone
2.1.2.4reference_wrapper invocationdone
2.1.2.5reference_wrapper helper functionsdone
2.2Smart pointersdone
2.2.1Additions to header <memory> synopsisdone
2.2.2Class bad_weak_ptrdone
2.2.3Class template shared_ptrdone1
2.2.3.1shared_ptr constructorsdone
2.2.3.2shared_ptr destructordone
2.2.3.3shared_ptr assignmentdone
2.2.3.4shared_ptr modifiersdone
2.2.3.5shared_ptr observersdone
2.2.3.6shared_ptr comparisondone
2.2.3.7shared_ptr I/Odone
2.2.3.8shared_ptr specialized algorithmsdone
2.2.3.9shared_ptr castsdone
2.2.3.10get_deleterdone
2.2.4Class template weak_ptrdone
2.2.4.1weak_ptr constructorsdone
2.2.4.2weak_ptr destructordone
2.2.4.3weak_ptr assignmentdone
2.2.4.4weak_ptr modifiersdone
2.2.4.5weak_ptr observersdone
2.2.4.6weak_ptr comparisondone
2.2.4.7weak_ptr specialized algorithmsdone
2.2.5Class template enable_shared_from_thisdone
3Function objects
3.1Definitionsdone
3.2Additions to <functional> synopsisdone
3.3Requirementsdone
3.4Function return typesdone
3.5Function template mem_fndone
3.6Function object bindersdone
3.6.1Class template is_bind_expressiondone
3.6.2Class template is_placeholderdone
3.6.3Function template binddone
3.6.4Placeholdersdone
3.7Polymorphic function wrappersdone
3.7.1Class bad_function_calldone
3.7.1.1bad_function_call constructordone
3.7.2Class template functiondone
3.7.2.1function construct/copy/destroydone
3.7.2.2function modifiersdone
3.7.2.3function capacitydone
3.7.2.4function invocationdone
3.7.2.5function target accessdone
3.7.2.6undefined operatorsdone
3.7.2.7null pointer comparison operatorsdone
3.7.2.8specialized algorithmsdone
4Metaprogramming and type traits
4.1Requirementsdone
4.2Header <type_traits> synopsisdone
4.3Helper classesdone
4.4General Requirementsdone
4.5Unary Type Traitsdone
4.5.1Primary Type Categoriesdone
4.5.2Composite type traitsdone
4.5.3Type propertiesdone
4.6Relationships between typesdone
4.7Transformations between typesdone
4.7.1Const-volatile modificationsdone
4.7.2Reference modificationsdone
4.7.3Array modificationsdone
4.7.4Pointer modificationsdone
4.8Other transformationsdone
4.9Implementation requirementsdone
5Numerical facilities
5.1Random number generationdone
5.1.1Requirementsdone
5.1.2Header <random> synopsisdone
5.1.3Class template variate_generatordone
5.1.4Random number engine class templatesdone
5.1.4.1Class template linear_congruentialdone
5.1.4.2Class template mersenne_twisterdone
5.1.4.3Class template subtract_with_carrydone
5.1.4.4Class template subtract_with_carry_01done
5.1.4.5Class template discard_blockdone
5.1.4.6Class template xor_combinedoneoperator()() per N2079
5.1.5Engines with predefined parametersdone
5.1.6Class random_devicedone
5.1.7Random distribution class templatesdone
5.1.7.1Class template uniform_intdone
5.1.7.2Class bernoulli_distributiondone
5.1.7.3Class template geometric_distributiondone
5.1.7.4Class template poisson_distributiondone
5.1.7.5Class template binomial_distributiondone
5.1.7.6Class template uniform_realdone
5.1.7.7Class template exponential_distributiondone
5.1.7.8Class template normal_distributiondone
5.1.7.9Class template gamma_distributiondone
5.2Mathematical special functionsdone
5.2.1Additions to header <cmath> synopsisdone
5.2.1.1associated Laguerre polynomialsdone
5.2.1.2associated Legendre functionsdone
5.2.1.3beta functiondone
5.2.1.4(complete) elliptic integral of the first kinddone
5.2.1.5(complete) elliptic integral of the second kinddone
5.2.1.6(complete) elliptic integral of the third kinddone
5.2.1.7confluent hypergeometric functionsdone
5.2.1.8regular modified cylindrical Bessel functionsdone
5.2.1.9cylindrical Bessel functions (of the first kind)done
5.2.1.10irregular modified cylindrical Bessel functionsdone
5.2.1.11cylindrical Neumann functionsdone
5.2.1.12(incomplete) elliptic integral of the first kinddone
5.2.1.13(incomplete) elliptic integral of the second kinddone
5.2.1.14(incomplete) elliptic integral of the third kinddone
5.2.1.15exponential integraldone
5.2.1.16Hermite polynomialsdone
5.2.1.17hypergeometric functionsdone
5.2.1.18Laguerre polynomialsdone
5.2.1.19Legendre polynomialsdone
5.2.1.20Riemann zeta functiondone
5.2.1.21spherical Bessel functions (of the first kind)done
5.2.1.22spherical associated Legendre functionsdone
5.2.1.23spherical Neumann functionsdone
5.2.2Additions to header <math.h> synopsisdone
6Containers
6.1Tuple typesdone
6.1.1Header <tuple> synopsisdone
6.1.2Additions to header <utility> synopsisdone
6.1.3Class template tupledone
6.1.3.1Constructiondone
6.1.3.2Tuple creation functionsdone
6.1.3.3Tuple helper classesdone
6.1.3.4Element accessdone
6.1.3.5Relational operatorsdone
6.1.4Pairsdone
6.2Fixed size arraydone
6.2.1Header <array> synopsisdone
6.2.2Class template arraydone
6.2.2.1array constructors, copy, and assignmentdone
6.2.2.2array specialized algorithmsdone
6.2.2.3array sizedone
6.2.2.4Zero sized arraysdone
6.2.2.5Tuple interface to class template arraydone
6.3Unordered associative containersdone
6.3.1Unordered associative container requirementsdone
6.3.1.1Exception safety guaranteesdone
6.3.2Additions to header <functional> synopsisdone
6.3.3Class template hashdone
6.3.4Unordered associative container classesdone
6.3.4.1Header <unordered_set> synopsisdone
6.3.4.2Header <unordered_map> synopsisdone
6.3.4.3Class template unordered_setdone
6.3.4.3.1unordered_set constructorsdone
6.3.4.3.2unordered_set swapdone
6.3.4.4Class template unordered_mapdone
6.3.4.4.1unordered_map constructorsdone
6.3.4.4.2unordered_map element accessdone
6.3.4.4.3unordered_map swapdone
6.3.4.5Class template unordered_multisetdone
6.3.4.5.1unordered_multiset constructorsdone
6.3.4.5.2unordered_multiset swapdone
6.3.4.6Class template unordered_multimapdone
6.3.4.6.1unordered_multimap constructorsdone
6.3.4.6.2unordered_multimap swapdone
7Regular expressions
7.1Definitionsmissing
7.2Requirementsmissing
7.3Regular expressions summarymissing
7.4Header <regex> synopsismissing
7.5Namespace tr1::regex_constantsmissing
7.5.1Bitmask Type syntax_option_typemissing
7.5.2Bitmask Type regex_constants::match_flag_typemissing
7.5.3Implementation defined error_typemissing
7.6Class regex_errormissing
7.7Class template regex_traitsmissing
7.8Class template basic_regexmissing
7.8.1basic_regex constantsmissing
7.8.2basic_regex constructorsmissing
7.8.3basic_regex assignmissing
7.8.4basic_regex constant operationsmissing
7.8.5basic_regex localemissing
7.8.6basic_regex swapmissing
7.8.7basic_regex non-member functionsmissing
7.8.7.1basic_regex non-member swapmissing
7.9Class template sub_matchmissing
7.9.1sub_match membersmissing
7.9.2sub_match non-member operatorsmissing
7.10Class template match_resultsmissing
7.10.1match_results constructorsmissing
7.10.2match_results sizemissing
7.10.3match_results element accessmissing
7.10.4match_results formattingmissing
7.10.5match_results allocatormissing
7.10.6match_results swapmissing
7.11Regular expression algorithmsmissing
7.11.1exceptionsmissing
7.11.2regex_matchmissing
7.11.3regex_searchmissing
7.11.4regex_replacemissing
7.12Regular expression Iteratorsmissing
7.12.1Class template regex_iteratormissing
7.12.1.1regex_iterator constructorsmissing
7.12.1.2regex_iterator comparisonsmissing
7.12.1.3regex_iterator dereferencemissing
7.12.1.4regex_iterator incrementmissing
7.12.2Class template regex_token_iteratormissing
7.12.2.1regex_token_iterator constructorsmissing
7.12.2.2regex_token_iterator comparisonsmissing
7.12.2.3regex_token_iterator dereferencemissing
7.12.2.4regex_token_iterator incrementmissing
7.13Modified ECMAScript regular expression grammarmissing
8C compatibility
8.1Additions to header <complex>done
8.1.1Synopsisdone
8.1.2Function acosdone
8.1.3Function asindone
8.1.4Function atandone
8.1.5Function acoshdone
8.1.6Function asinhdone
8.1.7Function atanhdone
8.1.8Function fabsdone
8.1.9Additional Overloadsdone
8.2Header <ccomplex>missingDR 551
8.3Header <complex.h>missingDR 551
8.4Additions to header <cctype>done
8.4.1Synopsisdone
8.4.2Function isblankdone
8.5Additions to header <ctype.h>done
8.6Header <cfenv>done
8.6.1Synopsisdone
8.6.2Definitionsdone
8.7Header <fenv.h>done
8.8Additions to header <cfloat>done
8.9Additions to header <float.h>done
8.10Additions to header <ios>missing
8.10.1Synopsismissing
8.10.2Function hexfloatmissing
8.11Header <cinttypes>done
8.11.1SynopsisdoneDR 557
8.11.2Definitionsdone
8.12Header <inttypes.h>done
8.13Additions to header <climits>done
8.14Additions to header <limits.h>done
8.15Additions to header <locale>missing
8.16Additions to header <cmath>done
8.16.1Synopsisdone
8.16.2Definitionsdone
8.16.3Function template definitionsdone
8.16.4Additional overloadsdoneDR 568; DR 550
8.17Additions to header <math.h>done
8.18Additions to header <cstdarg>done
8.19Additions to header <stdarg.h>done
8.20The header <cstdbool>done
8.21The header <stdbool.h>done
8.22The header <cstdint>done
8.22.1Synopsisdone
8.22.2Definitionsdone
8.23The header <stdint.h>done
8.24Additions to header <cstdio>done
8.24.1Synopsisdone
8.24.2Definitionsdone
8.24.3Additional format specifiersdoneC library responsibility
8.24.4Additions to header <stdio.h>done
8.25Additions to header <cstdlib>done
8.25.1Synopsisdone
8.25.2Definitionsdone
8.25.3Function absdone
8.25.4Function divdone
8.26Additions to header <stdlib.h>done
8.27Header <ctgmath>doneDR 551
8.28Header <tgmath.h>doneDR 551
8.29Additions to header <ctime>doneC library responsibility
8.30Additions to header <cwchar>done
8.30.1Synopsisdone
8.30.2Definitionsdone
8.30.3Additional wide format specifiersdoneC library responsibility
8.31Additions to header <wchar.h>done
8.32Additions to header <cwctype>done
8.32.1Synopsisdone
8.32.2Function iswblankdone
8.33Additions to header <wctype.h>done
- -

Footnotes

- -
    - -
  1. - - The shared_ptr implementation uses some code from the - Boost - shared_ptr library. -
    2. - -
- -

-Please send FSF & GNU inquiries & questions to -gnu@gnu.org. -There are also other ways -to contact the FSF. -

- -

-These pages are maintained by -the GCC team. -

- -
-For questions related to the use of GCC, please consult these web -pages and the GCC manuals. If -that fails, the gcc-help@gcc.gnu.org -mailing list might help.
-Please send comments on these web pages and the development of GCC to our -developer mailing list at gcc@gnu.org -or gcc@gcc.gnu.org. All of our lists -have public archives. -
- -

-Copyright (C) Free Software Foundation, Inc., -51 Franklin St, Fifth Floor, Boston, MA 02110, USA. -

-

-Verbatim copying and distribution of this entire article is -permitted in any medium, provided this notice is preserved. -

- - - - - - -
- Last modified 2006-10-01 - - - Valid XHTML 1.0 - -
- - - diff --git a/libstdc++-v3/doc/html/18_support/howto.html b/libstdc++-v3/doc/html/18_support/howto.html deleted file mode 100644 index d7ea434db2df..000000000000 --- a/libstdc++-v3/doc/html/18_support/howto.html +++ /dev/null @@ -1,435 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 18: Library Support - - - - - - - - - -

Chapter 18: Library Support

- -

Chapter 18 deals with the functions called and objects created - automatically during the course of a program's existence. -

-

While we can't reproduce the contents of the Standard here (you need to - get your own copy from your nation's member body; see our homepage for - help), we can mention a couple of changes in what kind of support a C++ - program gets from the Standard Library. -

- - - -
-

Contents

- - -
- - - -

Types

-

All the types that you're used to in C are here in one form or - another. The only change that might affect people is the type of - NULL: while it is required to be a macro, the definition of that - macro is not allowed to be (void*)0, which is - often used in C. -

-

In g++, NULL is #define'd to be __null, a magic keyword - extension of g++. -

-

The biggest problem of #defining NULL to be something like - "0L" is that the compiler will view that as a long integer - before it views it as a pointer, so overloading won't do what you - expect. (This is why g++ has a magic extension, so that NULL is - always a pointer.) -

-

In his book - 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:
-     template<class T>               // convertible to any type
-       operator T*() const           // of null non-member
-       { return 0; }                 // pointer...
-
-     template<class C, class T>      // or any type of null
-       operator T C::*() const       // member pointer...
-       { return 0; }
-
-   private:
-     void operator&() const;         // whose address can't be
-                                     // taken (see Item 27)...
-
-   } NULL;                           // and whose name is NULL
-
-

(Cribbed from the published version of - the - Effective C++ CD, reproduced here with permission.) -

-

If you aren't using g++ (why?), but you do have a compiler which - supports member function templates, then you can use this definition - of NULL (be sure to #undef any existing versions). It only helps if - you actually use NULL in function calls, though; if you make a call of - foo(0); instead of foo(NULL);, then you're back - where you started. -

-

Added Note: When we contacted Dr. Meyers to ask - permission to - 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 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 - after all). The ctor can have an empty body; it just needs to be - there. (Stupid requirement? We think so too, and this will probably - be changed in the language itself.) -

-

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

- -
-

Implementation properties

-

<limits>

-

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 specializations of the - template class numeric_limits, documented - here - and defined as follows: -

- 
-   template<typename T> struct class {
-      static const bool is_specialized;
-      static T max() throw();
-      static T min() throw();
-
-      static const int digits;
-      static const int digits10;
-      static const bool is_signed;
-      static const bool is_integer;
-      static const bool is_exact;
-      static const int radix;
-      static T epsilon() throw();
-      static T round_error() throw();
-
-      static const int min_exponent;
-      static const int min_exponent10;
-      static const int max_exponent;
-      static const int max_exponent10;
-
-      static const bool has_infinity;
-      static const bool has_quiet_NaN;
-      static const bool has_signaling_NaN;
-      static const float_denorm_style has_denorm;
-      static const bool has_denorm_loss;
-      static T infinity() throw();
-      static T quiet_NaN() throw();
-      static T denorm_min() throw();
-
-      static const bool is_iec559;
-      static const bool is_bounded;
-      static const bool is_modulo;
-
-      static const bool traps;
-      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 - the destructors of automatic nor static objects, so if you're depending - on those to do cleanup, it isn't going to happen. (The functions - registered with atexit() don't get called either, so you - can forget about that possibility, too.) -

-

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

-
    -
  1. Static objects are destroyed in reverse order of their creation. -
    2. -
  2. Functions registered with atexit() are called in - reverse order of registration, once per registration call. - (This isn't actually new.) -
    3. -
  3. The previous two actions are "interleaved," that is, - given this pseudocode: - 
    -              extern "C or C++" void  f1 (void);
-              extern "C or C++" void  f2 (void);
-
-              static Thing obj1;
-              atexit(f1);
-              static Thing obj2;
-              atexit(f2);
-
    - 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. -
    4. -
-

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 - the xatexit/xexit combination from libiberty, which has no such limit. -

-

Return to top of page or - 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()
-   {
-       std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
-       ...
-
-       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 - then the output from what() will be included. -

-

Any replacement termination function is required to kill the program - without returning; this one calls abort. -

-

For example: -

- 
-   #include <exception>
-   #include <stdexcept>
-
-   struct argument_error : public std::runtime_error
-   {  
-     argument_error(const std::string& s): std::runtime_error(s) { }
-   };
-
-   int main(int argc)
-   {
-     std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
-     if (argc > 5)
-       throw argument_error("argc is greater than 5!");
-     else
-       throw argc;
-   }
-
-

In GCC 3.1 and later, this gives -

- 
-   % ./a.out
-   terminate called after throwing a `int'
-   Aborted
-   % ./a.out f f f f f f f f f f f
-   terminate called after throwing an instance of `argument_error'
-   what(): argc is greater than 5!
-   Aborted
-   %
-

The 'Aborted' line comes from the call to abort(), of course. -

-

UPDATE: Starting with GCC 3.4, this is the default - termination handler; nothing need be done to use it. To go back to - the previous "silent death" method, simply include - <exception> and <cstdlib>, - and call -

- 
-       std::set_terminate(std::abort);
- -

- This function will attempt to write to stderr. If your application - closes stderr or redirects it to an inappropriate location, - __verbose_terminate_handler will behave in an - unspecified manner. -

- -

Return to top of page or - 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 - 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 - completeness' sake.) -

-

Remember that it is perfectly okay to call delete on a - NULL pointer! Nothing happens, by definition. That is not the - same thing as deleting a pointer twice. -

-

By default, if one of the "throwing news" can't - allocate the memory requested, it tosses an instance of a - 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;
-   static PFV    old_handler;
-
-   void my_new_handler ()
-   {
-       delete[] safety;
-       popup_window ("Dude, you are running low on heap memory.  You
-                      should, like, close some windows, or something.
-                      The next time you run out, we're gonna burn!");
-       set_new_handler (old_handler);
-       return;
-   }
-
-   int main ()
-   {
-       safety = new char[500000];
-       old_handler = set_new_handler (&my_new_handler);
-       ...
-   }
-
-

bad_alloc is derived from the base exception - class defined in Chapter 19. -

-

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

- -
-

RTTI, the ABI, and demangling

-

If you have read the source - documentation for namespace abi then you are aware - of the cross-vendor C++ ABI which we use. One of the exposed - functions is the one which we use for demangling in programs like - c++filt, and you can use it yourself as well. -

-

(The function itself might use different demanglers, but that's the - whole point of abstract interfaces. If we change the implementation, - you won't notice.) -

-

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>
-
-struct empty { };
-
-template <typename T, int N>
-  struct bar { };
-
-
-int main()
-{
-  int     status;
-  char   *realname;
-
-  // exception classes not in <stdexcept>, thrown by the implementation
-  // instead of the user
-  std::bad_exception  e;
-  realname = abi::__cxa_demangle(e.what(), 0, 0, &status);
-  std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n';
-  free(realname);
-
-
-  // typeid
-  bar<empty,17>          u;
-  const std::type_info  &ti = typeid(u);
-
-  realname = abi::__cxa_demangle(ti.name(), 0, 0, &status);
-  std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n';
-  free(realname);
-
-  return 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 - use crummy memory management facilities, so don't forget to free() - the returned char array.) -

-

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

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/19_diagnostics/howto.html b/libstdc++-v3/doc/html/19_diagnostics/howto.html deleted file mode 100644 index 90a60b3bca5f..000000000000 --- a/libstdc++-v3/doc/html/19_diagnostics/howto.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 19: Diagnostics - - - - - - - - - -

Chapter 19: Diagnostics

- -

Chapter 19 deals with program diagnostics, such as exceptions - and assertions. You know, all the things we wish weren't even - necessary at all. -

- - - -
-

Contents

- - -
- - - -

Adding data to exceptions

-

The standard exception classes carry with them a single string as - data (usually describing what went wrong or where the 'throw' took - place). It's good to remember that you can add your own data to - these exceptions when extending the hierarchy: -

- 
-   struct My_Exception : public std::runtime_error
-   {
-     public:
-       My_Exception (const string& whatarg)
-           : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
-       int  errno_at_time_of_throw() const { return e; }
-       DBID id_of_thing_that_threw() const { return id; }
-     protected:
-       int    e;
-       DBID   id;     // some user-defined type
-   };
-
-

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

- -
-

Concept checkers -- new and improved!

-

Better taste! Less fat! Literally!

-

In 1999, SGI added concept checkers to their implementation - of the STL: code which checked the template parameters of - instantiated pieces of the STL, in order to insure that the parameters - being used met the requirements of the standard. For example, - the Standard requires that types passed as template parameters to - vector be "Assignable" (which means what you think - it means). The checking was done during compilation, and none of - the code was executed at runtime. -

-

Unfortunately, the size of the compiler files grew significantly - as a result. The checking code itself was cumbersome. And bugs - were found in it on more than one occasion. -

-

The primary author of the checking code, Jeremy Siek, had already - 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 - GNU C++ library. -

-

The new version imposes a much smaller space overhead on the generated - object file. The checks are also cleaner and easier to read and - understand. -

-

They are off by default for all versions of GCC from 3.0 to 3.4 (the - latest release at the time of writing). - They can be enabled at configure time with - --enable-concept-checks. - You can enable them on a per-translation-unit basis with - #define _GLIBCXX_CONCEPT_CHECKS for GCC 3.4 and higher - (or with #define _GLIBCPP_CONCEPT_CHECKS for versions - 3.1, 3.2 and 3.3). -

- -

Please note that the upcoming C++ standard has first-class - support for template parameter constraints based on concepts in the core - language. This will obviate the need for the library-simulated concept - checking described above. -

- -

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

- - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/20_util/allocator.html b/libstdc++-v3/doc/html/20_util/allocator.html deleted file mode 100644 index 951c12df36d4..000000000000 --- a/libstdc++-v3/doc/html/20_util/allocator.html +++ /dev/null @@ -1,554 +0,0 @@ - - - - - - - - - - Allocators and allocation - - - - - - - -

Allocators and allocation

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/20_util/allocator.html. -

- -

- To the libstdc++ homepage. -

- - -
-

The C++ Standard encapsulates memory management characteristics - for strings, container classes, and parts of iostreams in a - template class called std::allocator. This class, and - base classes of it, are the superset of available free store - ("heap") management classes. -

- -

- Standard requirements -

-

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 - chars 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 - are: - 
    -      T*    allocate   (size_type n, const void* hint = 0);
-      void  deallocate (T* p, size_type n);
    - (This is a simplification; the real signatures use nested typedefs.) - 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 -
    • -
- -

Complete details cam be found in the C++ standard, look in - [20.4 Memory]. -

- -

- 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 - time the container releases memory. This method may be - slower - than caching the allocations and re-using previously-allocated - memory, but has the advantage of working correctly across a wide - variety of hardware and operating systems, including large - clusters. The __gnu_cxx::new_allocator implements - the simple operator new and operator delete semantics, while __gnu_cxx::malloc_allocator implements much the same thing, only with the C language functions std::malloc and std::free. -

- -

Another approach is to use intelligence within the allocator class -to cache allocations. This extra machinery can take a variety of -forms: a bitmap index, an index into an exponentially increasing -power-of-two-sized buckets, or simpler fixed-size pooling cache. The -cache is shared among all the containers in the program: when your -program's std::vector<int> gets cut in half and frees a bunch of -its storage, that memory can be reused by the private -std::list<WonkyWidget> brought in from a KDE library that you -linked against. And operators new and delete are not always called to -pass the memory on, either, which is a speed bonus. Examples of -allocators that use these techniques -are __gnu_cxx::bitmap_allocator, __gnu_cxx::pool_allocator, -and __gnu_cxx::__mt_alloc. -

- -

Depending on the implementation techniques used, the underlying -operating system, and compilation environment, scaling caching -allocators can be tricky. In particular, order-of-destruction and -order-of-creation for memory pools may be difficult to pin down with -certainty, which may create problems when used with plugins or loading -and unloading shared objects in memory. As such, using caching -allocators on systems that do not -support abi::__cxa_atexit is not recommended. -

- -

Versions of libstdc++ prior to 3.4 cache allocations in a memory - pool, instead of passing through to call the global allocation - operators (ie, __gnu_cxx::pool_allocator). More - recent versions default to the - simpler __gnu_cxx::new_allocator. -

- -

- Implementation details of std::allocator -

-

The implementation of std::allocator has continued - to evolve through successive releases. Here's a brief history. -

- -
- 3.0, 3.1, 3.2, 3.3 -
-

During this period, all allocators were written to the SGI - style, and all STL containers expected this interface. This - interface had a traits class called _Alloc_traits that - attempted to provide more information for compile-time allocation - selection and optimization. This traits class had another allocator - wrapper, __simple_alloc<T,A>, which was a - wrapper around another allocator, A, which itself is an allocator - for instances of T. But wait, there's more: - __allocator<T,A> is another adapter. Many of - the provided allocator classes were SGI style: such classes can be - changed to a conforming interface with this wrapper: - __allocator<T, __alloc> is thus the same as - allocator<T>. -

- -

The class std::allocator use the typedef - __alloc to select an underlying allocator that - satisfied memory allocation requests. The selection of this - underlying allocator was not user-configurable. -

- -
- 3.4 -
-

For this and later releases, the only allocator interface that - is support is the standard C++ interface. As such, all STL - containers have been adjusted, and all external allocators have - been modified to support this change. Because of this, - __simple_alloc, __allocator, __alloc, and - _Alloc_traits have all been removed. -

- -

The class std::allocator just has typedef, - constructor, and rebind members. It inherits from one of the - high-speed extension allocators, covered below. Thus, all - allocation and deallocation depends on the base class. -

- -

The base class that std::allocator is derived from - is not user-configurable. -

- -
- How the default allocation strategy is selected. -
-

It's difficult to pick an allocation strategy that will provide - maximum utility, without excessively penalizing some behavior. In - fact, it's difficult just deciding which typical actions to measure - for speed. -

- -

Three synthetic benchmarks have been created that provide data - that is used to compare different C++ allocators. These tests are: -

- -
    -
  • Insertion. Over multiple iterations, various STL container - objects have elements inserted to some maximum amount. A variety - of allocators are tested. - Test source for sequence - and associative - containers. -
    • - -
  • Insertion and erasure in a multi-threaded environment. - This test shows the ability of the allocator to reclaim memory - on a pre-thread basis, as well as measuring thread contention - for memory resources. - Test source - here. -
    • - -
  • A threaded producer/consumer model. - Test source for - sequence - and - associative - containers. -
    • -
- -
- Disabling memory caching. -
-

In use, std::allocator may allocate and deallocate - using implementation-specified strategies and heuristics. Because of - this, every call to an allocator object's allocate - member function may not actually call the global operator new. This - situation is also duplicated for calls to the - deallocate member function. -

- -

This can be confusing. -

- -

In particular, this can make debugging memory errors more - difficult, especially when using third party tools like valgrind or - debug versions of new. -

- -

There are various ways to solve this problem. One would be to - use a custom allocator that just called operators new - and delete directly, for every - allocation. (See include/ext/new_allocator.h, for instance.) - However, that option would involve changing source code to use the a - non-default allocator. Another option is to force the default - allocator to remove caching and pools, and to directly allocate - with every call of allocate and directly deallocate - with every call of deallocate, regardless of - efficiency. As it turns out, this last option is available, - although the exact mechanism has evolved with time. -

- -

For GCC releases from 2.95 through the 3.1 series, defining - __USE_MALLOC on the gcc command line would change the - default allocation strategy to instead use malloc and - free. See - this note - for details as to why this was something needing improvement. -

- -

Starting with GCC 3.2, and continued in the 3.3 series, to - globally disable memory caching within the library for the - default allocator, merely set GLIBCPP_FORCE_NEW (at this time, - with any value) in the system's environment before running the - program. If your program crashes with GLIBCPP_FORCE_NEW in the - environment, it likely means that you linked against objects - built against the older library. Code to support this extension - is fully compatible with 3.2 code if GLIBCPP_FORCE_NEW is not in - the environment. -

- -

As it turns out, the 3.4 code base continues to use this - mechanism, only the environment variable has been changed to - GLIBCXX_FORCE_NEW. -

- -

- Other allocators -

-

Several other allocators are provided as part of this - implementation. The location of the extension allocators and their - names have changed, but in all cases, functionality is - equivalent. Starting with gcc-3.4, all extension allocators are - standard style. Before this point, SGI style was the norm. Because of - this, the number of template arguments also changed. Here's a simple - chart to track the changes. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Allocator (3.4)Header (3.4)Allocator (3.[0-3])Header (3.[0-3])
__gnu_cxx::new_allocator<T><ext/new_allocator.h>std::__new_alloc<memory>
__gnu_cxx::malloc_allocator<T><ext/malloc_allocator.h>std::__malloc_alloc_template<int><memory>
__gnu_cxx::debug_allocator<T><ext/debug_allocator.h>std::debug_alloc<T><memory>
__gnu_cxx::__pool_alloc<T><ext/pool_allocator.h>std::__default_alloc_template<bool,int><memory>
__gnu_cxx::__mt_alloc<T><ext/mt_allocator.h>
__gnu_cxx::bitmap_allocator<T><ext/bitmap_allocator.h>
- -

Releases after gcc-3.4 have continued to add to the collection - of available allocators. All of these new allocators are - standard-style. The following table includes details, along with - the first released version of GCC that included the extension allocator. -

- - - - - - - - - - - - - - - - - -
AllocatorIncludeVersion
__gnu_cxx::array_allocator<T><ext/array_allocator.h>4.0.0
__gnu_cxx::throw_allocator<T><ext/throw_allocator.h>4.2.0
- -

More details on each of these extension allocators follows.

-
    -
  • new_allocator -

    Simply wraps ::operator new - and ::operator delete. -

    -
    • -
  • malloc_allocator -

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

    -
    • -
  • array_allocator -

    Allows allocations of known and fixed sizes using existing - global or external storage allocated via construction of - std::tr1::array objects. By using this allocator, fixed size - containers (including std::string) can be used without - instances calling ::operator new and - ::operator delete. This capability allows the - use of STL abstractions without runtime complications or - overhead, even in situations such as program startup. For - usage examples, please consult the libstdc++ testsuite. -

    -
    • -
  • debug_allocator -

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

    -
    • -
  • throw_allocator -

    Includes memory tracking and marking abilities as well as hooks for - throwing exceptinos at configurable intervals (including random, - all, none). -

    -
    • -
  • __pool_alloc -

    A high-performance, single pool allocator. The reusable - memory is shared among identical instantiations of this type. - It calls through ::operator new to obtain new memory - when its lists run out. If a client container requests a block - larger than a certain threshold size, then the pool is bypassed, - and the allocate/deallocate request is passed to - ::operator new directly.

    - -

    For versions of __pool_alloc after 3.4.0, there is - only one template parameter, as per the standard. -

    - -

    Older versions of this class take a boolean template parameter, - called thr, and an integer template parameter, - called inst. -

    - -

    The inst number is used to track additional memory - pools. The point of the number is to allow multiple - instantiations of the classes without changing the semantics at - all. All three of -

    - - 
    -    typedef  __pool_alloc<true,0>    normal;
-    typedef  __pool_alloc<true,1>    private;
-    typedef  __pool_alloc<true,42>   also_private;
    -

    behave exactly the same way. However, the memory pool for each type - (and remember that different instantiations result in different types) - remains separate. -

    -

    The library uses 0 in all its instantiations. If you - wish to keep separate free lists for a particular purpose, use a - different number. -

    -

    The thr boolean determines whether the pool should - be manipulated atomically or not. When thr=true, the allocator - is is threadsafe, while thr=false, and is slightly faster but - unsafe for multiple threads. -

    - -

    For thread-enabled configurations, the pool is locked with a - single big lock. In some situations, this implementation detail may - result in severe performance degredation. -

    - -

    (Note that the GCC thread abstraction layer allows us to provide safe - zero-overhead stubs for the threading routines, if threads were - disabled at configuration time.) -

    - -
    • - -
  • __mt_alloc -

    A high-performance - fixed-size allocator. It has its own documentation, found here. -

    -
    • - -
  • bitmap_allocator -

    A high-performance allocator that uses a bit-map to keep track - of the used and unused memory locations. It has its own - documentation, found here. -

    -
    • -
- - -

- Using a specific allocator -

-

You can specify different memory management schemes on a - per-container basis, by overriding the default - Allocator template parameter. For example, an easy - (but non-portable) method of specifying that only malloc/free - should be used instead of the default node allocator is: -

- 
-    std::list <int, __gnu_cxx::malloc_allocator<int> >  malloc_list;
- Likewise, a debugging form of whichever allocator is currently in use: - 
-    std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > >  debug_deque;
- - -

- Writing custom allocators -

-

Writing a portable C++ allocator would dictate that the - interface would look much like the one specified for - std::allocator. Additional member functions, but not - subtractions, would be permissible. -

- -

Probably the best place to start would be to copy one of the - extension allocators already shipped with libstdc++: say, - new_allocator . -

- - -

- Bibliography / Further Reading -

-

- ISO/IEC 14882:1998 Programming languages - C++ [20.4 Memory] -

- -

- Austern, Matt, C/C++ Users Journal. - The Standard Librarian: What Are Allocators Good - For? -

- -

- Berger, Emery, - The Hoard memory allocator -

- -

- Berger, Emery with Ben Zorn & Kathryn McKinley, OOPSLA 2002 - Reconsidering Custom Memory Allocation -

- -

- Kreft, Klaus and Angelika Langer, C++ Report, June 1998 - Allocator Types -

- -

- Stroustrup, Bjarne, 19.4 Allocators, The C++ Programming - Language, Special Edition, Addison Wesley, Inc. 2000 -

- -

- Yen, Felix, Yalloc: A Recycling C++ Allocator -

- -
-

Return to the top of the page or - to the libstdc++ homepage. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/20_util/howto.html b/libstdc++-v3/doc/html/20_util/howto.html deleted file mode 100644 index fb02aa169fb1..000000000000 --- a/libstdc++-v3/doc/html/20_util/howto.html +++ /dev/null @@ -1,234 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 20: General Utilities - - - - - - - - - - -

Chapter 20: General Utilities

- -

Chapter 20 deals with utility classes and functions, such as - the oft-debated auto_ptr<>. -

- - - -
-

Contents

- - -
- - - -

auto_ptr is not omnipotent

-

I'm not going to try and explain all of the fun and delicious - things that can happen with misuse of the auto_ptr class template - (called AP here), nor am I going to try and teach you how to use - AP safely in the presence of copying. The AP class is a really - nifty idea for a smart pointer, but it is one of the dumbest of - all the smart pointers -- and that's fine. -

-

AP is not meant to be a supersmart solution to all resource - leaks everywhere. Neither is it meant to be an effective form - of garbage collection (although it can help, a little bit). - And it can not be used for arrays! -

-

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;
-
-    extern function_taking_MyClass_pointer (MyClass*);
-    extern some_throwable_function ();
-
-    void func (int data)
-    {
-        APMC  ap (new MyClass(data));
-
-        some_throwable_function();   // this will throw an exception
-
-        function_taking_MyClass_pointer (ap.get());
-    }
-
-

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 - 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 - own auto_array_ptr for that situation (in fact, this has - been done many times; check the mailing lists, Usenet, Boost, etc). -

-

Return to top of page or - 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. - 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 - the AP being copied must change, which in turn means that the - copy ctors of AP do not take const objects. -

-

The resulting rule is simple: Never ever use a container of - auto_ptr objects. The standard says that "undefined" - behavior is the result, but it is guaranteed to be messy. -

-

To prevent you from doing this to yourself, the - concept checks built - in to this implementation will issue an error if you try to - compile code like this: -

- 
-    #include <vector>
-    #include <memory>
-    
-    void f()
-    {
-        std::vector< std::auto_ptr<int> >   vec_ap_int;
-    }
-
-

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 - the wheel, we will refer you to the introduction to the functor - concept written by SGI as part of their STL, in - their - http://www.sgi.com/tech/stl/functors.html. -

-

Return to top of page or - 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 - type T2; they may be the same type, but you don't get anything - extra if they are. The two members can be accessed directly, as - .first and .second. -

-

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 - and second getting y. -

-

There is a copy constructor, but it requires that your compiler - handle member function templates: -

- 
-    template <class U, class V> pair (const pair<U,V>& p);
-
-

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 - of two pair<T1,T2>s is defined as both first - members comparing equal and both second members comparing - equal; this simply delegates responsibility to the respective - 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 - 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 - 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);
-
- -

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

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/20_util/shared_ptr.html b/libstdc++-v3/doc/html/20_util/shared_ptr.html deleted file mode 100644 index 6df2e6de635a..000000000000 --- a/libstdc++-v3/doc/html/20_util/shared_ptr.html +++ /dev/null @@ -1,419 +0,0 @@ - - - - - - - - - Notes on the shared_ptr implementation. - - - - - - - -

-Notes on the shared_ptr implementation. -

- -prepared by Jonathan Wakely on November 11, 2007 - - -

-1. Abstract -

-

-The shared_ptr class template stores a pointer, usually obtained via new, -and implements shared ownership semantics. -

- -

-2. What the standard says -

- -
-20.6.6.2 - Class template shared_ptr [util.smartptr.shared] -
- -

-The standard deliberately doesn't require a reference-counted implementation, -allowing other techniques such as a circular-linked-list. -

- -

-At the time of writing the C++0x working paper doesn't mention how threads -affect shared_ptr, but it is likely to follow the existing practice set by -boost::shared_ptr. The shared_ptr in libstdc++ is derived -from Boost's, so the same rules apply. -

- -

-3. Problems with shared_ptr: TR1 vs C++0x, thread safety. -

- -

-The interface of tr1::shared_ptr was extended for C++0x with -support for rvalue-references and the other features from N2351. As -with other libstdc++ headers shared by TR1 and C++0x, boost_shared_ptr.h -uses conditional compilation, based on the macros _GLIBCXX_INCLUDE_AS_CXX0X -and _GLIBCXX_INCLUDE_AS_TR1, to enable and disable features. -

- -

-C++0x-only features are: rvalue-ref/move support, allocator support, -aliasing constructor, make_shared & allocate_shared. Additionally, the -constructors taking auto_ptr parameters are deprecated in C++0x mode. -

- -

-The -Thread -Safety section of the Boost shared_ptr documentation says "shared_ptr -objects offer the same level of thread safety as built-in types." -The implementation must ensure that concurrent updates to separate shared_ptr -instances are correct even when those instances share a reference count e.g. -

-
-shared_ptr<A> a(new A);
-shared_ptr<A> b(a);
-
-// Thread 1     // Thread 2
-   a.reset();      b.reset();
-
-

-The dynamically-allocated object must be destroyed by exactly one of the -threads. Weak references make things even more interesting. -The shared state used to implement shared_ptr must be transparent to the -user and invariants must be preserved at all times. -The key pieces of shared state are the strong and weak reference counts. -Updates to these need to be atomic and visible to all threads to ensure -correct cleanup of the managed resource (which is, after all, shared_ptr's -job!) -On multi-processor systems memory synchronisation may be needed so that -reference-count updates and the destruction of the managed resource are -race-free. -

- -

-The function _Sp_counted_base::_M_add_ref_lock(), called when -obtaining a shared_ptr from a weak_ptr, has to test if the managed -resource still exists and either increment the reference count or throw -std::bad_weak_ptr. -In a multi-threaded program there is a potential race condition if the last -reference is dropped (and the managed resource destroyed) between testing -the reference count and incrementing it, which could result in a shared_ptr -pointing to invalid memory. -

-

-The Boost shared_ptr (as used in GCC) features a clever lock-free algorithm -to avoid the race condition, but this relies on the processor supporting -an atomic Compare-And-Swap instruction. For other platforms there -are fall-backs using mutex locks. Boost (as of version 1.35) includes -several different implementations and the preprocessor selects one based -on the compiler, standard library, platform etc. For the version of -shared_ptr in libstdc++ the compiler and library are fixed, which makes -things much simpler: we have an atomic CAS or we don't, see Lock Policy -below for details. -

- -

-4. Design and Implementation Details -

- -

-The shared_ptr code in libstdc++ was kindly donated to GCC by the Boost -project and the original authors of the code. The basic design and -algorithms are from Boost, the notes below describe details specific to -the GCC implementation. Names have been uglified in this implementation, -but the design should be recognisable to anyone familiar with the Boost -1.32 shared_ptr. -

- -

-The basic design is an abstract base class, _Sp_counted_base that -does the reference-counting and calls virtual functions when the count -drops to zero. -Derived classes override those functions to destroy resources in a context -where the correct dynamic type is known. This is an application of the -technique known as type erasure. -

- -

-C++0x and TR1 Implementations -

- -

-The classes derived from _Sp_counted_base (see Class Hierarchy -below) and __shared_count are implemented separately for C++0x -and TR1, in bits/boost_sp_shared_count.h and -tr1/boost_sp_shared_count.h respectively. All other classes -including _Sp_counted_base are shared by both implementations. -

- -

-The TR1 implementation is considered relatively stable, so is unlikely to -change unless bug fixes require it to. If the code that is common to both -C++0x and TR1 modes needs to diverge further then it might be necessary to -duplicate additional classes and only make changes to the C++0x versions. -

- -

-Lock Policy -

- -

-Libstdc++ has a single _Sp_counted_base class, which is a -template parameterized on the enum __gnu_cxx::_Lock_policy. -The entire family of classes is parameterized on the lock policy, right up -to __shared_ptr, __weak_ptr and -__enable_shared_from_this. The actual -std::shared_ptr class inherits from __shared_ptr -with the lock policy parameter selected automatically based on the thread -model and platform that libstdc++ is configured for, so that the best -available template specialization will be used. This design is necessary -because it would not be conforming for std::shared_ptr to have -an extra template parameter, even if it had a default value. -The available policies are: -

- -
-
_S_Atomic
-
-Selected when GCC supports a builtin atomic compare-and-swap -operation on the target processor (see -Atomic -Builtins.) -The reference counts are maintained using a lock-free algorithm and GCC's -atomic builtins, which provide the required memory synchronisation. -
-
_S_Mutex
-
-The _Sp_counted_base specialization for this policy contains a mutex, -which is locked in add_ref_lock(). This policy is used when GCC's atomic -builtins aren't available so explicit memory barriers are needed in places. -
-
_S_Single
-
-This policy uses a non-reentrant add_ref_lock() with no locking. It is -used when libstdc++ is built without --enable-threads. -
-
- -

-For all three policies, reference count increments and decrements are done -via the functions in <ext/atomicity.h>, which detect if the -program is multi-threaded. -If only one thread of execution exists in the program then less expensive -non-atomic operations are used. -

- -

-Class Hierarchy -

- -

-A shared_ptr<T> contains a pointer of type T* -and an object of type __shared_count. The shared_count contains -a pointer of type _Sp_counted_base* which points to the object -that maintains the reference-counts and destroys the managed resource. -

- -
-
_Sp_counted_base<Lp>
-
-The base of the hierarchy is parameterized on the lock policy alone. -_Sp_counted_base doesn't depend on the type of pointer being managed, -it only maintains the reference counts and calls virtual functions when -the counts drop to zero. The managed object is destroyed when the last -strong reference is dropped, but the _Sp_counted_base itself must exist -until the last weak reference is dropped. -
-
_Sp_counted_base_impl<Ptr, Deleter, Lp>
-
-Inherits from _Sp_counted_base and stores a pointer of type Ptr -and a deleter of type Deleter. _Sp_deleter is -used when the user doesn't supply a custom deleter. Unlike Boost's, this -default deleter is not "checked" because GCC already issues a warning if -delete is used with an incomplete type. -This is the only derived type used by tr1::shared_ptr<Ptr> -and it is never used by std::shared_ptr, which uses one of -the following types, depending on how the shared_ptr is constructed. -
-
_Sp_counted_ptr<Ptr, Lp>
-
-Inherits from _Sp_counted_base and stores a pointer of type Ptr, -which is passed to delete when the last reference is dropped. -This is the simplest form and is used when there is no custom deleter or -allocator. -
-
_Sp_counted_deleter<Ptr, Deleter, Alloc>
-
-Inherits from _Sp_counted_ptr and adds support for custom deleter and -allocator. Empty Base Optimization is used for the allocator. This class -is used even when the user only provides a custom deleter, in which case -std::allocator is used as the allocator. -
-
_Sp_counted_ptr_inplace<Tp, Alloc, Lp>
-
-Used by allocate_shared and make_shared. -Contains aligned storage to hold an object of type Tp, -which is constructed in-place with placement new. -Has a variadic template constructor allowing any number of arguments to -be forwarded to Tp's constructor. -Unlike the other _Sp_counted_* classes, this one is parameterized on the -type of object, not the type of pointer; this is purely a convenience -that simplifies the implementation slightly. -
-
- -

-Related functions and classes -

- -
-
dynamic_pointer_cast, static_pointer_cast, -const_pointer_cast
-
-As noted in N2351, these functions can be implemented non-intrusively using -the alias constructor. However the aliasing constructor is only available -in C++0x mode, so in TR1 mode these casts rely on three non-standard -constructors in shared_ptr and __shared_ptr. -In C++0x mode these constructors and the related tag types are not needed. -
-
enable_shared_from_this
-
-The clever overload to detect a base class of type -enable_shared_from_this comes straight from Boost. -There is an extra overload for __enable_shared_from_this to -work smoothly with __shared_ptr<Tp, Lp> using any lock -policy. -
-
make_shared, allocate_shared
-
-make_shared simply forwards to allocate_shared -with std::allocator as the allocator. -Although these functions can be implemented non-intrusively using the -alias constructor, if they have access to the implementation then it is -possible to save storage and reduce the number of heap allocations. The -newly constructed object and the _Sp_counted_* can be allocated in a single -block and the standard says implementations are "encouraged, but not required," -to do so. This implementation provides additional non-standard constructors -(selected with the type _Sp_make_shared_tag) which create an -object of type _Sp_counted_ptr_inplace to hold the new object. -The returned shared_ptr<A> needs to know the address of the -new A object embedded in the _Sp_counted_ptr_inplace, -but it has no way to access it. -This implementation uses a "covert channel" to return the address of the -embedded object when get_deleter<_Sp_make_shared_tag>() -is called. Users should not try to use this. -As well as the extra constructors, this implementation also needs some -members of _Sp_counted_deleter to be protected where they could otherwise -be private. -
-
- -

-5. Examples -

- -

-Examples of use can be found in the testsuite, under -testsuite/tr1/2_general_utilities/shared_ptr. -

- -

-6. Unresolved Issues -

- -

-The resolution to C++ Standard Library issue 674, -"shared_ptr interface changes for consistency with N1856" will need to be -implemented after it is accepted into the working paper. Issue 743 -might also require changes. -

- -

-The _S_single policy uses atomics when used in MT code, because it uses -the same dispatcher functions that check __gthread_active_p(). This could be -addressed by providing template specialisations for some members of -_Sp_counted_base<_S_single>. -

- -

-Unlike Boost, this implementation does not use separate classes for the -pointer+deleter and pointer+deleter+allocator cases in C++0x mode, combining -both into _Sp_counted_deleter and using std::allocator when the user doesn't -specify an allocator. -If it was found to be beneficial an additional class could easily be added. -With the current implementation, the _Sp_counted_deleter and __shared_count -constructors taking a custom deleter but no allocator are technically -redundant and could be removed, changing callers to always specify an -allocator. If a separate pointer+deleter class was added the __shared_count -constructor would be needed, so it has been kept for now. -

- -

-The hack used to get the address of the managed object from -_Sp_counted_ptr_inplace::_M_get_deleter() is accessible to users. This -could be prevented if get_deleter<_Sp_make_shared_tag>() always -returned NULL, since the hack only needs to work at a lower level, not -in the public API. This wouldn't be difficult, but hasn't been done since -there is no danger of accidental misuse: users already know they are -relying on unsupported features if they refer to implementation details -such as _Sp_make_shared_tag. -

- -

-tr1::_Sp_deleter could be a private member of tr1::__shared_count but it -would alter the ABI. -

- -

-Exposing the alias constructor in TR1 mode could simplify the *_pointer_cast -functions. -Constructor could be private in TR1 mode, with the cast functions as friends. -

- -

-7. Acknowledgments -

-

-The original authors of the Boost shared_ptr, which is really nice code -to work with, Peter Dimov in particular for his help and invaluable advice -on thread safety. -Phillip Jordan and Paolo Carlini for the lock policy implementation. -

- - -

-8. Bibliography / Referenced Documents -

- -

-N2351 Improving shared_ptr for C++0x, Revision 2 -http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm -

- -

-N2456 C++ Standard Library Active Issues List (Revision R52) -http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html

-

-N2461 Working Draft, Standard for Programming Language C++ -http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf -

- -

-Boost C++ Libraries documentation - shared_ptr class template -http://boost.org/libs/smart_ptr/shared_ptr.htm -

- - - - diff --git a/libstdc++-v3/doc/html/21_strings/gotw29a.txt b/libstdc++-v3/doc/html/21_strings/gotw29a.txt deleted file mode 100644 index 9326604855e2..000000000000 --- a/libstdc++-v3/doc/html/21_strings/gotw29a.txt +++ /dev/null @@ -1,159 +0,0 @@ -From: herbs@cntc.com (Herb Sutter) -Subject: Guru of the Week #29: Solution -Date: 22 Jan 1998 00:00:00 GMT -Message-ID: <6a8q26$9qa@netlab.cs.rpi.edu> -Newsgroups: comp.lang.c++.moderated - - - .--------------------------------------------------------------------. - | Guru of the Week problems and solutions are posted regularly on | - | news:comp.lang.c++.moderated. For past problems and solutions | - | see the GotW archive at http://www.cntc.com. | - | Is there a topic you'd like to see covered? mailto:herbs@cntc.com | - `--------------------------------------------------------------------' -_______________________________________________________ - -GotW #29: Strings - -Difficulty: 7 / 10 -_______________________________________________________ - - ->Write a ci_string class which is identical to the ->standard 'string' class, but is case-insensitive in the ->same way as the C function stricmp(): - -The "how can I make a case-insensitive string?" -question is so common that it probably deserves its own -FAQ -- hence this issue of GotW. - -Note 1: The stricmp() case-insensitive string -comparison function is not part of the C standard, but -it is a common extension on many C compilers. - -Note 2: What "case insensitive" actually means depends -entirely on your application and language. For -example, many languages do not have "cases" at all, and -for languages that do you have to decide whether you -want accented characters to compare equal to unaccented -characters, and so on. This GotW provides guidance on -how to implement case-insensitivity for standard -strings in whatever sense applies to your particular -situation. - - -Here's what we want to achieve: - -> ci_string s( "AbCdE" ); -> -> // case insensitive -> assert( s == "abcde" ); -> assert( s == "ABCDE" ); -> -> // still case-preserving, of course -> assert( strcmp( s.c_str(), "AbCdE" ) == 0 ); -> assert( strcmp( s.c_str(), "abcde" ) != 0 ); - -The key here is to understand what a "string" actually -is in standard C++. If you look in your trusty string -header, you'll see something like this: - - typedef basic_string string; - -So string isn't really a class... it's a typedef of a -template. In turn, the basic_string<> template is -declared as follows, in all its glory: - - template, - class Allocator = allocator > - class basic_string; - -So "string" really means "basic_string, allocator >". We don't need -to worry about the allocator part, but the key here is -the char_traits part because char_traits defines how -characters interact and compare(!). - -basic_string supplies useful comparison functions that -let you compare whether a string is equal to another, -less than another, and so on. These string comparisons -functions are built on top of character comparison -functions supplied in the char_traits template. In -particular, the char_traits template supplies character -comparison functions named eq(), ne(), and lt() for -equality, inequality, and less-than comparisons, and -compare() and find() functions to compare and search -sequences of characters. - -If we want these to behave differently, all we have to -do is provide a different char_traits template! Here's -the easiest way: - - struct ci_char_traits : public char_traits - // just inherit all the other functions - // that we don't need to override - { - static bool eq( char c1, char c2 ) { - return tolower(c1) == tolower(c2); - } - - static bool ne( char c1, char c2 ) { - return tolower(c1) != tolower(c2); - } - - static bool lt( char c1, char c2 ) { - return tolower(c1) < tolower(c2); - } - - static int compare( const char* s1, - const char* s2, - size_t n ) { - return strnicmp( s1, s2, n ); - // if available on your compiler, - // otherwise you can roll your own - } - - static const char* - find( const char* s, int n, char a ) { - while( n-- > 0 && tolower(*s) != tolower(a) ) { - ++s; - } - return n >= 0 ? s : 0; - } - }; - -[N.B. A bug in the original code has been fixed for the -GCC documentation, the corrected code was taken from -Herb Sutter's book, Exceptional C++] - -And finally, the key that brings it all together: - - typedef basic_string ci_string; - -All we've done is created a typedef named "ci_string" -which operates exactly like the standard "string", -except that it uses ci_char_traits instead of -char_traits to get its character comparison -rules. Since we've handily made the ci_char_traits -rules case-insensitive, we've made ci_string itself -case-insensitive without any further surgery -- that -is, we have a case-insensitive string without having -touched basic_string at all! - -This GotW should give you a flavour for how the -basic_string template works and how flexible it is in -practice. If you want different comparisons than the -ones stricmp() and tolower() give you, just replace the -five functions shown above with your own code that -performs character comparisons the way that's -appropriate in your particular application. - - - -Exercise for the reader: - -Is it safe to inherit ci_char_traits from -char_traits this way? Why or why not? - - diff --git a/libstdc++-v3/doc/html/21_strings/howto.html b/libstdc++-v3/doc/html/21_strings/howto.html deleted file mode 100644 index bdc868a02dc4..000000000000 --- a/libstdc++-v3/doc/html/21_strings/howto.html +++ /dev/null @@ -1,472 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 21: Strings - - - - - - - - - -

Chapter 21: Strings

- -

Chapter 21 deals with the C++ strings library (a welcome relief). -

- - - -
-

Contents

- - -
- - - -

MFC's CString

-

A common lament seen in various newsgroups deals with the Standard - string class as opposed to the Microsoft Foundation Class called - CString. Often programmers realize that a standard portable - answer is better than a proprietary nonportable one, but in porting - their application from a Win32 platform, they discover that they - are relying on special functions offered by the CString class. -

-

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 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>
-
-   string f (string& incoming)     // incoming is "foo  N"
-   {
-       istringstream   incoming_stream(incoming);
-       string          the_word;
-       int             the_number;
-
-       incoming_stream >> the_word        // extract "foo"
-                       >> the_number;     // extract N
-
-       ostringstream   output_stream;
-       output_stream << "The word was " << the_word
-                     << " and 3*N was " << (3*the_number);
-
-       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:
-   
-   CString n_copies_of (const CString& foo, unsigned n)
-   {
-           CString tmp;
-           for (unsigned i = 0; i < n; i++)
-                   tmp += foo;
-           return tmp;
-   }
-   
-   This function is O(n^2), not O(n).  The reason is that each +=
-   causes a reallocation and copy of the existing string.  Microsoft
-   applications are full of this kind of thing (quadratic performance
-   on tasks that can be done in linear time) -- on the other hand,
-   we should be thankful, as it's created such a big market for high-end
-   ix86 hardware. :-)
-   
-   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 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++, their - string class is not. The SGI string is essentially - vector<char> and does not do any reference - counting like libstdc++'s does. (It is O(n), though.) - So if you're thinking about SGI's string or rope classes, - you're now looking at four possibilities: CString, the - 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 - discussions held on Usenet covered this topic in January of 1998. - Briefly, the challenge was, "write a 'ci_string' class which - 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
-   assert( s == "abcde" );
-   assert( s == "ABCDE" );
-
-   // 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 was posted on Usenet, and a revised version appears in - Herb Sutter's book Exceptional C++ and on his website as - GotW 29. -

-

See? Told you it was easy!

-

Added June 2000: The May 2000 issue of C++ Report - contains a fascinating - article by Matt Austern (yes, the Matt Austern) - on why case-insensitive comparisons are not as easy as they seem, - and why creating a class is the wrong way to go about it in - production code. (The GotW answer mentions one of the principle - difficulties; his article mentions more.) -

-

Basically, this is "easy" only if you ignore some things, - things which may be too important to your program to ignore. (I chose - to ignore them when originally writing this entry, and am surprised - that nobody ever called me on it...) The GotW question and answer - remain useful instructional tools, however. -

-

Added September 2000: James Kanze provided a link to a - Unicode - Technical Report discussing case handling, which provides some - very good information. -

-

Return to top of page or - 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 - destroys the character string on which it operates, and it requires - you to handle all the memory problems. But it does let the client - code decide what to use to break the string into pieces; it allows - you to choose the "whitespace," so to speak. -

-

A C++ implementation lets us keep the good things and fix those - annoyances. The implementation here is more intuitive (you only - call it once, not in a loop with varying argument), it does not - affect the original string at all, and all the memory allocation - is handled for you. -

-

It's called stringtok, and it's a template function. It's given - in this file in a less-portable form than - it could be, to keep this example simple (for example, see the - 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: -

- 
-   :this:
-   :is:
-   :a:
-   :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. -

-

As always, there is a price paid here, in that stringtok is not - as fast as strtok. The other benefits usually outweigh that, however. - Another version of stringtok is given - here, suggested by Chris King and tweaked by Petr Prikryl, - and this one uses the - transformation functions mentioned below. If you are comfortable - with reading the new function names, this version is recommended - as an example. -

-

Added February 2001: Mark Wilden pointed out that the - standard std::getline() function can be used with standard - istringstreams to perform - tokenizing as well. Build an istringstream from the input text, - and then use std::getline with varying delimiters (the three-argument - signature) to extract tokens into a string. -

-

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

- -
-

Simple transformations

-

Here are Standard, simple, and portable ways to perform common - transformations on a string instance, such as "convert - to all upper case." The word transformations is especially - apt, because the standard template function - transform<> is used. -

-

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>
-
-   struct ToLower
-   {
-     char operator() (char c) const  { return std::tolower(c); }
-   };
-
-   struct ToUpper
-   {
-     char operator() (char c) const  { return std::toupper(c); }
-   };
-
-   int main()
-   {
-     std::string  s ("Some Kind Of Initial Input Goes Here");
-
-     // Change everything into upper case
-     std::transform (s.begin(), s.end(), s.begin(), ToUpper());
-
-     // Change everything into lower case
-     std::transform (s.begin(), s.end(), s.begin(), ToLower());
-
-     // Change everything back into upper case, but store the
-     // result in a different string
-     std::string  capital_s;
-     capital_s.resize(s.size());
-     std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper());
-   }
-

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 - from the basic source character set, and there are only - 96 of those. Which means that not even all English text can be - represented (certain British spellings, proper names, and so forth). - So, if all your input forevermore consists of only those 96 - characters (hahahahahaha), then you're done. -

-

Note that the - ToUpper and ToLower function objects - are needed because toupper and tolower - are overloaded names (declared in <cctype> and - <locale>) so the template-arguments for - transform<> cannot be deduced, as explained in - this - message. - At minimum, you can write short wrappers like -

- 
-   char toLower (char c)
-   {
-      return std::tolower(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 - Correct Transformations, - which shows the final version of this code. (Thanks to James Kanze - for assistance and suggestions on all of this.) -

-

Another common operation is trimming off excess whitespace. Much - 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
-   string::size_type  notwhite = str.find_first_not_of(" \t\n");
-   str.erase(0,notwhite);
-
-   // trim trailing whitespace
-   notwhite = str.find_last_not_of(" \t\n"); 
-   str.erase(notwhite+1);
-

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

-

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

- -
-

Making strings of arbitrary character types

-

The std::basic_string is tantalizingly general, in that - it is parameterized on the type of the characters which it holds. - In theory, you could whip up a Unicode character class and instantiate - std::basic_string<my_unicode_char>, or assuming - that integers are wider than characters on your platform, maybe just - declare variables of type std::basic_string<int>. -

-

That's the theory. Remember however that basic_string has additional - type parameters, which take default arguments based on the character - type (called CharT here): -

- 
-      template <typename CharT,
-                typename Traits = char_traits<CharT>,
-                typename Alloc = allocator<CharT> >
-      class basic_string { .... };
-

Now, allocator<CharT> will probably Do The Right - Thing by default, unless you need to implement your own allocator - for your characters. -

-

But char_traits takes more work. The char_traits - template is declared but not defined. - That means there is only -

- 
-      template <typename CharT>
-        struct char_traits
-        {
-            static void foo (type1 x, type2 y);
-            ...
-        };
-

and functions such as char_traits<CharT>::foo() are not - actually defined anywhere for the general case. The C++ standard - permits this, because writing such a definition to fit all possible - CharT's cannot be done. -

-

The C++ standard also requires that char_traits be specialized for - instantiations of char and wchar_t, and it - is these template specializations that permit entities like - basic_string<char,char_traits<char>> to work. -

-

If you want to use character types other than char and wchar_t, - such as unsigned char and int, you will - need suitable specializations for them. For a time, in earlier - versions of GCC, there was a mostly-correct implementation that - let programmers be lazy but it broke under many situations, so it - was removed. GCC 3.4 introduced a new implementation that mostly - works and can be specialized even for int and other - built-in types. -

-

If you want to use your own special character class, then you have - a lot - of work to do, especially if you with to use i18n features - (facets require traits information but don't have a traits argument). -

-

Another example of how to specialize char_traits was given on the - mailing list and at a later date was put into the file - include/ext/pod_char_traits.h. We agree - that the way it's used with basic_string (scroll down to main()) - doesn't look nice, but that's because the - nice-looking first attempt turned out to not - be conforming C++, due to the rule that CharT must be a POD. - (See how tricky this is?) -

-

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

- -
-

Shrink-to-fit strings

- -

From GCC 3.4 calling s.reserve(res) on a - string s with res < s.capacity() will - reduce the string's capacity to std::max(s.size(), res). -

-

This behaviour is suggested, but not required by the standard. Prior - to GCC 3.4 the following alternative can be used instead -

- 
-      std::string(str.data(), str.size()).swap(str);
-
-

This is similar to the idiom for reducing a vector's - memory usage (see FAQ 5.9) but - the regular copy constructor cannot be used because libstdc++'s - string is Copy-On-Write. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/21_strings/stringtok_h.txt b/libstdc++-v3/doc/html/21_strings/stringtok_h.txt deleted file mode 100644 index 81d87a6efaf7..000000000000 --- a/libstdc++-v3/doc/html/21_strings/stringtok_h.txt +++ /dev/null @@ -1,102 +0,0 @@ -/* - * stringtok.h -- Breaks a string into tokens. This is an example for lib3. - * - * Template function looks like this: - * - * template - * void stringtok (Container &l, - * string const &s, - * char const * const ws = " \t\n"); - * - * A nondestructive version of strtok() that handles its own memory and can - * be broken up by any character(s). Does all the work at once rather than - * in an invocation loop like strtok() requires. - * - * Container is any type that supports push_back(a_string), although using - * list and deque are indicated due to their O(1) push_back. - * (I prefer deque<> because op[]/at() is available as well.) The first - * parameter references an existing Container. - * - * s is the string to be tokenized. From the parameter declaration, it can - * be seen that s is not affected. Since references-to-const may refer to - * temporaries, you could use stringtok(some_container, readline("")) when - * using the GNU readline library. - * - * The final parameter is an array of characters that serve as whitespace. - * Whitespace characters default to one or more of tab, space, and newline, - * in any combination. - * - * 'l' need not be empty on entry. On return, 'l' will have the token - * strings appended. - * - * - * [Example: - * list ls; - * stringtok (ls, " this \t is\t\n a test "); - * for (list::const_iterator i = ls.begin(); - * i != ls.end(); ++i) - * { - * cerr << ':' << (*i) << ":\n"; - * } - * - * would print - * :this: - * :is: - * :a: - * :test: - * -end example] - * - * pedwards@jaj.com May 1999 -*/ - - -#include -#include // for strchr - - -/***************************************************************** - * This is the only part of the implementation that I don't like. - * It can probably be improved upon by the reader... -*/ -namespace { - inline bool - isws (char c, char const * const wstr) - { - return (strchr(wstr,c) != NULL); - } -} - - -/***************************************************************** - * Simplistic and quite Standard, but a bit slow. This should be - * templatized on basic_string instead, or on a more generic StringT - * that just happens to support ::size_type, .substr(), and so on. - * I had hoped that "whitespace" would be a trait, but it isn't, so - * the user must supply it. Enh, this lets them break up strings on - * different things easier than traits would anyhow. -*/ -template -void -stringtok (Container &l, string const &s, char const * const ws = " \t\n") -{ - const string::size_type S = s.size(); - string::size_type i = 0; - - while (i < S) { - // eat leading whitespace - while ((i < S) && (isws(s[i],ws))) ++i; - if (i == S) return; // nothing left but WS - - // find end of word - string::size_type j = i+1; - while ((j < S) && (!isws(s[j],ws))) ++j; - - // add word - l.push_back(s.substr(i,j-i)); - - // set up for next loop - i = j+1; - } -} - - diff --git a/libstdc++-v3/doc/html/21_strings/stringtok_std_h.txt b/libstdc++-v3/doc/html/21_strings/stringtok_std_h.txt deleted file mode 100644 index 2f3d7e073684..000000000000 --- a/libstdc++-v3/doc/html/21_strings/stringtok_std_h.txt +++ /dev/null @@ -1,39 +0,0 @@ -/* - * Same as stringtok_h.txt, but doesn't (visiably) use C functions. -*/ - -#include - -// The std:: prefix is not used here, for readability, and a line like -// "using namespace std;" is dangerous to have in a header file. - -template -void -stringtok (Container &container, string const &in, - const char * const delimiters = " \t\n") -{ - const string::size_type len = in.length(); - string::size_type i = 0; - - while ( i < len ) - { - // eat leading whitespace - i = in.find_first_not_of (delimiters, i); - if (i == string::npos) - return; // nothing left but white space - - // find the end of the token - string::size_type j = in.find_first_of (delimiters, i); - - // push token - if (j == string::npos) { - container.push_back (in.substr(i)); - return; - } else - container.push_back (in.substr(i, j-i)); - - // set up for next loop - i = j + 1; - } -} - diff --git a/libstdc++-v3/doc/html/22_locale/codecvt.html b/libstdc++-v3/doc/html/22_locale/codecvt.html deleted file mode 100644 index c760c098b5cc..000000000000 --- a/libstdc++-v3/doc/html/22_locale/codecvt.html +++ /dev/null @@ -1,595 +0,0 @@ - - - - - - - - - - Notes on the codecvt implementation. - - - - - - - -

- Notes on the codecvt implementation. -

-

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

- -

-1. Abstract -

-

-The standard class codecvt attempts to address conversions between -different character encoding schemes. In particular, the standard -attempts to detail conversions between the implementation-defined wide -characters (hereafter referred to as wchar_t) and the standard type -char that is so beloved in classic "C" (which can now be referred to -as narrow characters.) This document attempts to describe how the GNU -libstdc++ implementation deals with the conversion between wide and -narrow characters, and also presents a framework for dealing with the -huge number of other encodings that iconv can convert, including -Unicode and UTF8. Design issues and requirements are addressed, and -examples of correct usage for both the required specializations for -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 -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 -native character set. codecvt<char,char,mbstate_t> implements a -degenerate conversion; it does not convert at -all. codecvt<wchar_t,char,mbstate_t> converts between the native -character sets for tiny and wide characters. Instantiations on -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 -(yet useful and widely used) conversions need to do so through the -third template parameter, stateT.

- -

-Two: The required conversions, by specifying mbstate_t as the third -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 -

-Probably the most frequently asked question about code conversion is: -"So dudes, what's the deal with Unicode strings?" The dude part is -optional, but apparently the usefulness of Unicode strings is pretty -widely appreciated. Sadly, this specific encoding (And other useful -encodings like UTF8, UCS4, ISO 8859-10, etc etc etc) are not mentioned -in the C++ standard. - -

-In particular, the simple implementation detail of wchar_t's size -seems to repeatedly confound people. Many systems use a two byte, -unsigned integral type to represent wide characters, and use an -internal encoding of Unicode or UCS2. (See AIX, Microsoft NT, Java, -others.) Other systems, use a four byte, unsigned integral type to -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: -

- -

-The thought that all one needs to convert between two arbitrary -codesets is two types and some kind of state argument is -unfortunate. In particular, encodings may be stateless. The naming of -the third parameter as stateT is unfortunate, as what is really needed -is some kind of generalized type that accounts for the issues that -abstract encodings will need. The minimum information that is required -includes: -

- -
    -
  • -

    - Identifiers for each of the codesets involved in the conversion. For -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,
-ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
-ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
-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 -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 require explicit endian-ness. As such, some kind - of endian marker or other byte-order marker will be necessary. See - "Footnotes for C/C++ developers" in Haible for more information on - UCS-2/Unicode endian issues. (Summary: big endian seems most likely, - however implementations, most notably Microsoft, vary.) -
    • - -
  • - Types representing the conversion state, for conversions involving - the machinery in the "C" library, or the conversion descriptor, for - 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. -

- -In addition, multi-threaded and multi-locale environments also impact -the design and requirements for code conversions. In particular, they -affect the required specialization codecvt<wchar_t, char, mbstate_t> -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 -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 -locale for all the "C" functions referenced above. For something like -C++ iostreams (where codecvt is explicitly used) the notion of -multiple locales is fundamental. In practice, most users may not run -into this limitation. However, as a quality of implementation issue, -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++ 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 -

-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++ implements a partial specialization -of the codecvt class with and iconv wrapper class, encoding_state as the -third template parameter. -

- -

-This implementation should be standards conformant. First of all, the -standard explicitly points out that instantiations on the third -template parameter, stateT, are the proper way to implement -non-required conversions. Second of all, the standard says (in Chapter -17) that partial specializations of required classes are a-ok. Third -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 encoding_state 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 encoding_state: -

- -

- -encoding_state() : __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). -

- -

- -encoding_state(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 -conversions are not standardized. Because of this, the thought of -mandating and or enforcing some set of pre-determined valid -identifiers seems iffy: thus, a more practical (and non-migraine -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 encoding_state 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 encoding_state object has been -properly initialized. If the string literals describing the desired -internal and external encoding are not valid, initialization will -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. -

- -

- -encoding_state(const encoding_state&) - -

-

-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, encoding_state> is consistent with other -codecvt usage. -

- -

-6. Examples -

- -
    -
  • - 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 encoding_state                          state_type;
-  typedef codecvt<int_type, ext_type, state_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 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;
-
-  // construct a locale object with the specialized facet.
-  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); 
-  // convert between const char* and unicode strings
-  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);
-  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 -
    • -
- -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
    • -
- -

-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? -
    • - -
  • - 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? -
      • -
    -
    • -
- -

-8. Acknowledgments -

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

- -Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. Character Set Handling" and "7 Locales and Internationalization" - -

-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/doc/html/22_locale/ctype.html b/libstdc++-v3/doc/html/22_locale/ctype.html deleted file mode 100644 index e52f8353bd9d..000000000000 --- a/libstdc++-v3/doc/html/22_locale/ctype.html +++ /dev/null @@ -1,166 +0,0 @@ - - - - - - - - - - Notes on the ctype implementation. - - - - - - - -

- Notes on the ctype implementation. -

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

-1. Abstract -

-

-Woe is me. -

- -

-2. What the standard says -

- - -

-3. Problems with "C" ctype : global locales, termination. -

- -

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

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

- -

-5. Examples -

- -
-  typedef ctype<char> cctype;
-
- -More information can be found in the following testcases: -
    -
  • 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 different types than char, wchar_t?
    • - -
  • codecvt/ctype overlap: narrow/widen
    • - -
  • 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?
    • - -
  • 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 -

- -Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. Character Set Handling" and "7 Locales and Internationalization" - -

-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/doc/html/22_locale/howto.html b/libstdc++-v3/doc/html/22_locale/howto.html deleted file mode 100644 index 3709a6fac972..000000000000 --- a/libstdc++-v3/doc/html/22_locale/howto.html +++ /dev/null @@ -1,240 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 22: Localization - - - - - - - - - - - - - - - -

Chapter 22: Localization

- -

Chapter 22 deals with the C++ localization facilities. -

- - - - -
-

Contents

- - - - -
-

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

- -

The following is the abstract from the implementation notes: -

-
- The standard class codecvt attempts to address conversions between - different character encoding schemes. In particular, the standard - attempts to detail conversions between the implementation-defined - wide characters (hereafter referred to as wchar_t) and the standard - type char that is so beloved in classic "C" (which can - now be referred to as narrow characters.) This document attempts - to describe how the GNU libstdc++ implementation deals with the - conversion between wide and narrow characters, and also presents a - framework for dealing with the huge number of other encodings that - iconv can convert, including Unicode and UTF8. Design issues and - requirements are addressed, and examples of correct usage for both - the required specializations for wide and narrow characters and the - 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. -

- -
-

Bjarne Stroustrup on Locales

-

Dr. Bjarne Stroustrup has released a - pointer - to Appendix D of his book, - The C++ - Programming Language (3rd Edition). It is a detailed - description of locales and how to use them. -

-

He also writes: -

-
- Please note that I still consider this detailed description of - locales beyond the needs of most C++ programmers. It is written - with experienced programmers in mind and novices will do best to - 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 - do I do <foo> to a character string?" where <foo> is - a task such as changing all the letters to uppercase, to lowercase, - testing for digits, etc. A skilled and conscientious programmer - will follow the question with another, "And how do I make the - code portable?" -

-

(Poor innocent programmer, you have no idea the depths of trouble - you are getting yourself into. 'Twould be best for your sanity if - you dropped the whole idea and took up basket weaving instead. No? - Fine, you asked for it...) -

-

The task of changing the case of a letter or classifying a character - as numeric, graphical, etc., all depends on the cultural context of the - program at runtime. So, first you must take the portability question - into account. Once you have localized the program to a particular - natural language, only then can you perform the specific task. - Unfortunately, specializing a function for a human language is not - as simple as declaring - extern "Danish" int tolower (int); . -

-

The C++ code to do all this proceeds in the same way. First, a locale - is created. Then member functions of that locale are called to - perform minor tasks. Continuing the example from Chapter 21, we wish - to use the following convenience functions: -

- 
-   namespace std {
-     template <class charT>
-       charT
-       toupper (charT c, const locale& loc) const;
-     template <class charT>
-       charT
-       tolower (charT c, const locale& loc) const;
-   }
-

- This function extracts the appropriate "facet" from the - locale loc and calls the appropriate member function of that - facet, passing c as its argument. The resulting character - is returned. -

-

For the C/POSIX locale, the results are the same as calling the - classic C toupper/tolower function that was used in previous - examples. For other locales, the code should Do The Right Thing. -

-

Of course, these functions take a second argument, and the - transformation algorithm's operator argument can only take a single - parameter. So we write simple wrapper structs to handle that. -

-

The next-to-final version of the code started in Chapter 21 looks like: -

- 
-   #include <iterator>    // for back_inserter
-   #include <locale>
-   #include <string>
-   #include <algorithm>
-   #include <cctype>      // old <ctype.h>
-
-   struct ToUpper
-   {
-       ToUpper(std::locale const& l) : loc(l) {;}
-       char operator() (char c) const  { return std::toupper(c,loc); }
-   private:
-       std::locale const& loc;
-   };
-   
-   struct ToLower
-   {
-       ToLower(std::locale const& l) : loc(l) {;}
-       char operator() (char c) const  { return std::tolower(c,loc); }
-   private:
-       std::locale const& loc;
-   };
-   
-   int main ()
-   {
-      std::string  s("Some Kind Of Initial Input Goes Here");
-      ToUpper      up(std::locale::classic());
-      ToLower      down(std::locale::classic());
-   
-      // Change everything into upper case.
-      std::transform(s.begin(), s.end(), s.begin(), up);
-   
-      // Change everything into lower case.
-      std::transform(s.begin(), s.end(), s.begin(), down);
-   
-      // Change everything back into upper case, but store the
-      // result in a different string.
-      std::string  capital_s;
-      std::transform(s.begin(), s.end(), std::back_inserter(capital_s), up);
-   }
-

The ToUpper and ToLower structs can be - generalized for other character types by making operator() - a member function template. -

-

The final version of the code uses bind2nd to eliminate - the wrapper structs, but the resulting code is tricky. I have not - shown it here because no compilers currently available to me will - handle it. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/22_locale/locale.html b/libstdc++-v3/doc/html/22_locale/locale.html deleted file mode 100644 index 57ef5b4e981c..000000000000 --- a/libstdc++-v3/doc/html/22_locale/locale.html +++ /dev/null @@ -1,543 +0,0 @@ - - - - - - - - - - Notes on the locale implementation. - - - - - - - -

- Notes on the locale implementation. -

- -prepared by Benjamin Kosnik (bkoz@redhat.com) on October 14, 2002 - - -

-1. Abstract -

-

-Describes the basic locale object, including nested -classes id, facet, and the reference-counted implementation object, -class _Impl. -

- -

-2. What the standard says -

-Class locale is non-templatized and has two distinct types nested -inside of it: - -
- -class facet -22.1.1.1.2 Class locale::facet - -
- -

-Facets actually implement locale functionality. For instance, a facet -called numpunct is the data objects that can be used to query for the -thousands separator is in the German locale. -

- -Literally, a facet is strictly defined: -
    -
  • containing the following public data member: -

    - static locale::id id; -

    -
    • - -
  • derived from another facet: -

    - class gnu_codecvt: public std::ctype<user-defined-type> -

    -
    • -
- -

-Of interest in this class are the memory management options explicitly -specified as an argument to facet's constructor. Each constructor of a -facet class takes a std::size_t __refs argument: if __refs == 0, the -facet is deleted when the locale containing it is destroyed. If __refs -== 1, the facet is not destroyed, even when it is no longer -referenced. -

- -
- -class id -22.1.1.1.3 - Class locale::id - -
- -

-Provides an index for looking up specific facets. -

- - -

-3. Interacting with "C" locales. -

- -

-Some help on determining the underlying support for locales on a system. -Note, this is specific to linux (and glibc-2.3.x) -

- -
    -
  • `locale -a` displays available locales. -
    -
    -af_ZA
-ar_AE
-ar_AE.utf8
-ar_BH
-ar_BH.utf8
-ar_DZ
-ar_DZ.utf8
-ar_EG
-ar_EG.utf8
-ar_IN
-ar_IQ
-ar_IQ.utf8
-ar_JO
-ar_JO.utf8
-ar_KW
-ar_KW.utf8
-ar_LB
-ar_LB.utf8
-ar_LY
-ar_LY.utf8
-ar_MA
-ar_MA.utf8
-ar_OM
-ar_OM.utf8
-ar_QA
-ar_QA.utf8
-ar_SA
-ar_SA.utf8
-ar_SD
-ar_SD.utf8
-ar_SY
-ar_SY.utf8
-ar_TN
-ar_TN.utf8
-ar_YE
-ar_YE.utf8
-be_BY
-be_BY.utf8
-bg_BG
-bg_BG.utf8
-br_FR
-bs_BA
-C
-ca_ES
-ca_ES@euro
-ca_ES.utf8
-ca_ES.utf8@euro
-cs_CZ
-cs_CZ.utf8
-cy_GB
-da_DK
-da_DK.iso885915
-da_DK.utf8
-de_AT
-de_AT@euro
-de_AT.utf8
-de_AT.utf8@euro
-de_BE
-de_BE@euro
-de_BE.utf8
-de_BE.utf8@euro
-de_CH
-de_CH.utf8
-de_DE
-de_DE@euro
-de_DE.utf8
-de_DE.utf8@euro
-de_LU
-de_LU@euro
-de_LU.utf8
-de_LU.utf8@euro
-el_GR
-el_GR.utf8
-en_AU
-en_AU.utf8
-en_BW
-en_BW.utf8
-en_CA
-en_CA.utf8
-en_DK
-en_DK.utf8
-en_GB
-en_GB.iso885915
-en_GB.utf8
-en_HK
-en_HK.utf8
-en_IE
-en_IE@euro
-en_IE.utf8
-en_IE.utf8@euro
-en_IN
-en_NZ
-en_NZ.utf8
-en_PH
-en_PH.utf8
-en_SG
-en_SG.utf8
-en_US
-en_US.iso885915
-en_US.utf8
-en_ZA
-en_ZA.utf8
-en_ZW
-en_ZW.utf8
-es_AR
-es_AR.utf8
-es_BO
-es_BO.utf8
-es_CL
-es_CL.utf8
-es_CO
-es_CO.utf8
-es_CR
-es_CR.utf8
-es_DO
-es_DO.utf8
-es_EC
-es_EC.utf8
-es_ES
-es_ES@euro
-es_ES.utf8
-es_ES.utf8@euro
-es_GT
-es_GT.utf8
-es_HN
-es_HN.utf8
-es_MX
-es_MX.utf8
-es_NI
-es_NI.utf8
-es_PA
-es_PA.utf8
-es_PE
-es_PE.utf8
-es_PR
-es_PR.utf8
-es_PY
-es_PY.utf8
-es_SV
-es_SV.utf8
-es_US
-es_US.utf8
-es_UY
-es_UY.utf8
-es_VE
-es_VE.utf8
-et_EE
-et_EE.utf8
-eu_ES
-eu_ES@euro
-eu_ES.utf8
-eu_ES.utf8@euro
-fa_IR
-fi_FI
-fi_FI@euro
-fi_FI.utf8
-fi_FI.utf8@euro
-fo_FO
-fo_FO.utf8
-fr_BE
-fr_BE@euro
-fr_BE.utf8
-fr_BE.utf8@euro
-fr_CA
-fr_CA.utf8
-fr_CH
-fr_CH.utf8
-fr_FR
-fr_FR@euro
-fr_FR.utf8
-fr_FR.utf8@euro
-fr_LU
-fr_LU@euro
-fr_LU.utf8
-fr_LU.utf8@euro
-ga_IE
-ga_IE@euro
-ga_IE.utf8
-ga_IE.utf8@euro
-gl_ES
-gl_ES@euro
-gl_ES.utf8
-gl_ES.utf8@euro
-gv_GB
-gv_GB.utf8
-he_IL
-he_IL.utf8
-hi_IN
-hr_HR
-hr_HR.utf8
-hu_HU
-hu_HU.utf8
-id_ID
-id_ID.utf8
-is_IS
-is_IS.utf8
-it_CH
-it_CH.utf8
-it_IT
-it_IT@euro
-it_IT.utf8
-it_IT.utf8@euro
-iw_IL
-iw_IL.utf8
-ja_JP.eucjp
-ja_JP.utf8
-ka_GE
-kl_GL
-kl_GL.utf8
-ko_KR.euckr
-ko_KR.utf8
-kw_GB
-kw_GB.utf8
-lt_LT
-lt_LT.utf8
-lv_LV
-lv_LV.utf8
-mi_NZ
-mk_MK
-mk_MK.utf8
-mr_IN
-ms_MY
-ms_MY.utf8
-mt_MT
-mt_MT.utf8
-nl_BE
-nl_BE@euro
-nl_BE.utf8
-nl_BE.utf8@euro
-nl_NL
-nl_NL@euro
-nl_NL.utf8
-nl_NL.utf8@euro
-nn_NO
-nn_NO.utf8
-no_NO
-no_NO.utf8
-oc_FR
-pl_PL
-pl_PL.utf8
-POSIX
-pt_BR
-pt_BR.utf8
-pt_PT
-pt_PT@euro
-pt_PT.utf8
-pt_PT.utf8@euro
-ro_RO
-ro_RO.utf8
-ru_RU
-ru_RU.koi8r
-ru_RU.utf8
-ru_UA
-ru_UA.utf8
-se_NO
-sk_SK
-sk_SK.utf8
-sl_SI
-sl_SI.utf8
-sq_AL
-sq_AL.utf8
-sr_YU
-sr_YU@cyrillic
-sr_YU.utf8
-sr_YU.utf8@cyrillic
-sv_FI
-sv_FI@euro
-sv_FI.utf8
-sv_FI.utf8@euro
-sv_SE
-sv_SE.iso885915
-sv_SE.utf8
-ta_IN
-te_IN
-tg_TJ
-th_TH
-th_TH.utf8
-tl_PH
-tr_TR
-tr_TR.utf8
-uk_UA
-uk_UA.utf8
-ur_PK
-uz_UZ
-vi_VN
-vi_VN.tcvn
-wa_BE
-wa_BE@euro
-yi_US
-zh_CN
-zh_CN.gb18030
-zh_CN.gbk
-zh_CN.utf8
-zh_HK
-zh_HK.utf8
-zh_TW
-zh_TW.euctw
-zh_TW.utf8
-
    -
    -
    • - -
  • `locale` displays environmental variables - that impact how locale("") will be deduced. - -
    -
    -LANG=en_US
-LC_CTYPE="en_US"
-LC_NUMERIC="en_US"
-LC_TIME="en_US"
-LC_COLLATE="en_US"
-LC_MONETARY="en_US"
-LC_MESSAGES="en_US"
-LC_PAPER="en_US"
-LC_NAME="en_US"
-LC_ADDRESS="en_US"
-LC_TELEPHONE="en_US"
-LC_MEASUREMENT="en_US"
-LC_IDENTIFICATION="en_US"
-LC_ALL=
-
    -
    -
    • -
- -

-From Josuttis, p. 697-698, which says, that "there is only *one* -relation (of the C++ locale mechanism) to the C locale mechanism: the -global C locale is modified if a named C++ locale object is set as the -global locale" (emphasis Paolo), that is: -

- std::locale::global(std::locale("")); - -

affects the C functions as if the following call was made:

- - std::setlocale(LC_ALL, ""); - -

-On the other hand, there is *no* viceversa, that is, calling setlocale -has *no* whatsoever on the C++ locale mechanism, in particular on the -working of locale(""), which constructs the locale object from the -environment of the running program, that is, in practice, the set of -LC_ALL, LANG, etc. variable of the shell. -

- - -

-4. Design -

- - -

-The major design challenge is fitting an object-orientated and -non-global locale 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. -

- -class _Impl -The internal representation of the std::locale object. - - -

-5. Examples -

- -More information can be found in the following testcases: -
    -
  • testsuite/22_locale/all
    • -
- -

-6. Unresolved Issues -

- -
    -
  • 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?
    • - -
  • 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?
    • -
- -

-7. Acknowledgments -

- -

-8. Bibliography / Referenced Documents -

- -Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. Character Set Handling" and "7 Locales and Internationalization" - -

-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/doc/html/22_locale/messages.html b/libstdc++-v3/doc/html/22_locale/messages.html deleted file mode 100644 index bb096c09e7f2..000000000000 --- a/libstdc++-v3/doc/html/22_locale/messages.html +++ /dev/null @@ -1,461 +0,0 @@ - - - - - - - - - - Notes on the messages implementation. - - - - - - - -

-Notes on the messages implementation. -

- -prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001 - - -

-1. Abstract -

-

-The std::messages facet implements message retrieval functionality -equivalent to Java's java.text.MessageFormat .using either GNU gettext -or IEEE 1003.1-200 functions. -

- -

-2. What the standard says -

-The std::messages facet is probably the most vaguely defined facet in -the standard library. It's assumed that this facility was built into -the standard library in order to convert string literals from one -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. - -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. -

-A couple of notes on the standard. - -

-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 -designed. The signature seems quite peculiar. Why specify a const -string& argument, for instance, instead of just const -char*? Or, why specify a const locale& argument that is -to be used in the 'get' member function? How, exactly, is this locale -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 -

-This is a relatively simple class, on the face of it. The standard -specifies very little in concrete terms, so generic implementations -that are conforming yet do very little are the norm. Adding -functionality that would be useful to programmers and comparable to -Java's java.text.MessageFormat takes a bit of work, and is highly -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. -

    -
    • -
- -

-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 -characters sets, depends on the ctype and perhaps the codecvt facet in -a given locale. In addition, underlying "C" library locale support is -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++.mo -

    -

    - cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.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. - -
    -#include <iostream>
-#include <locale>
-using namespace std;
-
-void test01()
-{
-  typedef messages<char>::catalog catalog;
-  const char* dir =
-  "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";  
-  const locale loc_de("de_DE");
-  const messages<char>& mssg_de = use_facet<messages<char> >(loc_de); 
-
-  catalog cat_de = mssg_de.open("libstdc++", loc_de, dir);
-  string s01 = mssg_de.get(cat_de, 0, 0, "please");
-  string s02 = mssg_de.get(cat_de, 0, 0, "thank you");
-  cout << "please in german:" << s01 << '\n';
-  cout << "thank you in german:" << s02 << '\n';
-  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
    • -
- -

-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. -
    • -
  • 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: - -

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

    -
    • -
- -

-7. Acknowledgments -

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

- -Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters -"7 Locales and Internationalization" - -

-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/doc/html/23_containers/howto.html b/libstdc++-v3/doc/html/23_containers/howto.html deleted file mode 100644 index c4b6eb856f58..000000000000 --- a/libstdc++-v3/doc/html/23_containers/howto.html +++ /dev/null @@ -1,457 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 23: Containers - - - - - - - - - -

Chapter 23: Containers

- -

Chapter 23 deals with container classes and what they offer. -

- - - -
-

Contents

- - -
- - - -

Making code unaware of the container/array difference

-

You're writing some code and can't decide whether to use builtin - arrays or some kind of container. There are compelling reasons - to use one of the container classes, but you're afraid that you'll - eventually run into difficulties, change everything back to arrays, - and then have to change all the code that uses those data types to - keep up with the change. -

-

If your code makes use of the standard algorithms, this isn't as - scary as it sounds. The algorithms don't know, nor care, about - the kind of "container" on which they work, since the - algorithms are only given endpoints to work with. For the container - classes, these are iterators (usually begin() and - end(), but not always). For builtin arrays, these are - the address of the first element and the - past-the-end element. -

-

Some very simple wrapper functions can hide all of that from the - rest of the code. For example, a pair of functions called - beginof can be written, one that takes an array, another - that takes a vector. The first returns a pointer to the first - element, and the second returns the vector's begin() - iterator. -

-

The functions should be made template functions, and should also - be declared inline. As pointed out in the comments in the code - below, this can lead to beginof being optimized out of - existence, so you pay absolutely nothing in terms of increased - 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 - of ints to a deque of ints and back again, without ever changing any - client code. -

-

This author has a collection of such functions, called "*of" - because they all extend the builtin "sizeof". It started - with some Usenet discussions on a transparent way to find the length - of an array. A simplified and much-reduced version for easier - reading is given here. -

-

Astute readers will notice two things at once: first, that the - container class is still a vector<T> instead of a - more general Container<T>. This would mean that - three functions for deque would have to be added, another - three for list, and so on. This is due to problems with - getting template resolution correct; I find it easier just to - 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. -

-

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)
-      {
-          std::bitset<n>   bits;
-          ....
-      }
-

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>.   It has - been pointed out a few times in newsgroups that N bits only takes up - (N/8) bytes on most systems, and division by a factor of eight is pretty - impressive when speaking of memory. Half a megabyte given over to a - bitset (recall that there is zero space overhead for housekeeping info; - it is known at compile time exactly how large the set is) will hold over - four million bits. If you're using those bits as status flags (e.g., - "changed"/"unchanged" flags), that's a lot - of state. -

-

You can then keep track of the "maximum bit used" during some - testing runs on representative data, make note of how many of those bits - really need to be there, and then reduce N to a smaller number. Leave - some extra space, of course. (If you plan to write code like the - incorrect example above, where the bitset is a local variable, then you - may have to talk your compiler into allowing that much stack space; - there may be zero space overhead, but it's all allocated inside the - object.) -

-

A container<bool>.   The Committee - made provision - for the space savings possible with that (N/8) usage previously mentioned, - so that you don't have to do wasteful things like - Container<char> or - Container<short int>. - Specifically, vector<bool> is required to be - specialized for that space savings. -

-

The problem is that vector<bool> doesn't behave like a - normal vector anymore. There have been recent journal articles which - discuss the problems (the ones by Herb Sutter in the May and - July/August 1999 issues of - C++ Report cover it well). Future revisions of the ISO C++ - Standard will change the requirement for vector<bool> - specialization. In the meantime, deque<bool> is - recommended (although its behavior is sane, you probably will not get - the space savings, but the allocation scheme is different than that - of vector). -

-

Extremely weird solutions.   If you have - access to - the compiler and linker at runtime, you can do something insane, like - figuring out just how many bits you need, then writing a temporary - source code file. That file contains an instantiation of - bitset - for the required number of bits, inside some wrapper functions with - unchanging signatures. Have your program then call the - compiler on that file using Position Independent Code, then open the - newly-created object file and load those wrapper functions. You'll have - an instantiation of bitset<N> for the exact - N - that you need at the time. Don't forget to delete the temporary files. - (Yes, this can be, and has been, done.) -

- -

This would be the approach of either a visionary genius or a raving - lunatic, depending on your programming and management style. Probably - the latter. -

-

Which of the above techniques you use, if any, are up to you and your - intended application. Some time/space profiling is indicated if it - really matters (don't just guess). And, if you manage to do anything - along the lines of the third category, the author would love to hear - from you... -

-

Also note that the implementation of bitset used in libstdc++ has - some extensions. -

-

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

- -
-

Containers and multithreading

-

This section discusses issues surrounding the design of - multithreaded applications which use Standard C++ containers. - All information in this section is current as of the gcc 3.0 - release and all later point releases. Although earlier gcc - releases had a different approach to threading configuration and - proper compilation, the basic code design rules presented here - were similar. For information on all other aspects of - 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 - discussion, libstdc++ configures the SGI STL implementation, - not you. This is quite different from how gcc pre-3.0 worked. - In particular, past advice was for people using g++ to - explicitly define _PTHREADS or other macros or port-specific - compilation options on the command line to get a thread-safe - 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++ 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 - fourth major paragraph of the first page mentioned above - ("For most clients,"...), which points out that - locking must nearly always be done outside the container, by - client code (that'd be you, not us). There is a notable - exceptions to this rule. Allocators called while a container or - element is constructed uses an internal lock obtained and - released solely within libstdc++ 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 - releases the lock. This could be templatized to a certain - extent, on the underlying container and/or a locking - mechanism. Trying to provide a catch-all general template - solution would probably be more trouble than it's worth. -

-

The STL implementation is currently configured to use the - high-speed caching memory allocator. Some people like to - test and/or normally run threaded programs with a different - default. For all details about how to globally override this - at application run-time see here. -

-

There is a better way (not standardized yet): It is possible to - force the malloc-based allocator on a per-case-basis for some - application code. The library team generally believes that this - is a better way to tune an application for high-speed using this - implementation of the STL. There is - more information on allocators here. -

-

Return to top of page or - 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 - to insert. The standard says that "t is inserted - as close as possible to the position just prior to - p." (Library DR #233 addresses this topic, referring to - N1780. - Since version 4.2 GCC implements the resolution to DR 233, so that - insertions happen as close as possible to the hint. For earlier releases - the hint was only used as described below. -

-

Here we'll describe how the hinting works in the libstdc++ - implementation, and what you need to do in order to take advantage of - it. (Insertions can change from logarithmic complexity to amortized - constant time, if the hint is properly used.) Also, since the current - implementation is based on the SGI STL one, these points may hold true - for other library implementations also, since the HP/SGI code is used - in a lot of places. -

-

In the following text, the phrases greater than and less - than refer to the results of the strict weak ordering imposed on - the container by its comparison object, which defaults to (basically) - "<". Using those phrases is semantically sloppy, but I - didn't want to get bogged down in syntax. I assume that if you are - intelligent enough to use your own comparison objects, you are also - intelligent enough to assign "greater" and "lesser" - 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 - by "not greater than." (Why not replace greater with - greater-than-or-equal-to? You probably could in your head, but the - mathematicians will tell you that it isn't the same thing.) -

-

If the conditions are not met, then the hint is not used, and the - insertion proceeds as if you had called a.insert(t) - instead. (Note that GCC releases prior to 3.0.2 - had a bug in the case with hint == begin() for the - map and set classes. You should not use a hint - argument in those releases.) -

-

This behavior goes well with other containers' insert() - functions which take an iterator: if used, the new item will be - inserted before the iterator passed as an argument, same as the other - containers. -

-

Note also that the hint in this implementation is a - one-shot. The older insertion-with-hint routines check the immediately - surrounding entries to ensure that the new item would in fact belong - there. If the hint does not point to the correct place, then no - further local searching is done; the search begins from scratch in - logarithmic time. -

-

Return to top of page or - 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 - about the problem: follow the library's "Links" from the - homepage, and from the C++ information "defect reflector" - link, select the library issues list. Issue number 116 describes the - problem. -

-

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

- 
-      std::bitset<5> b ( std::string("10110") );
-
- instead of - 
-      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 - linked lists would be to maintain an extra member variable containing - the list's size. This would require taking extra time to update that - variable (it would make splice() a linear time operation, for example), - and it would also make the list larger. Many list algorithms don't - require that extra word (algorithms that do require it might do better - with vectors than with lists), and, when it is necessary to maintain - an explicit size count, it's something that users can do themselves. -

-

This choice is permitted by the C++ standard. The standard says that - size() "should" be constant time, and "should" - does not mean the same thing as "shall". This is the - officially recommended ISO wording for saying that an implementation - 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)
-             ...
- Instead, you should write - 
-         if (L.empty())
-             ...
-
-

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

- -
-

Space overhead management for vectors

-

In - this - message to the list, Daniel Kostecky announced work on an - alternate form of std::vector that would support hints - on the number of elements to be over-allocated. The design was also - described, along with possible implementation choices. -

-

The first two alpha releases were announced - here - and - here. - The releases themselves are available at - - http://www.kotelna.sk/dk/sw/caphint/. -

-

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

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/23_containers/wrappers_h.txt b/libstdc++-v3/doc/html/23_containers/wrappers_h.txt deleted file mode 100644 index 53b59204220d..000000000000 --- a/libstdc++-v3/doc/html/23_containers/wrappers_h.txt +++ /dev/null @@ -1,48 +0,0 @@ - -/***************************************************************** - * Functions to help treat arrays in a uniform manner. These were - * inspired by a thread on comp.lang.c++.moderated, started by Dietmar - * Kuehl and contributed to by the rest of the entire planet. - * - * beginof (x), endof (x), lengthof (x) now accompany sizeof, where x - * can be either a container (currently only sequences) or a builtin - * array (/not/ a pointer). The beginof/endof are intended for use in - * the algorithms library, and lengthof is a "sizing" function. - * - * Note example: - * char an_array [17]; - * cerr << lengthof(an_array) << endl; - * produces assembly code of - * mov 17,register0 - * call ofstream_put - * i.e., the template function inlining really does work; g++ - * requires -O3 (or -finline-functions) before it does this, though. - * - * pedwards 13Nov98 -*/ -// beginof -template - inline typename vector::iterator beginof (vector &v) - { return v.begin(); } - -template - inline T* beginof (T (&array)[sz]) { return array; } - - -// endof -template - inline typename vector::iterator endof (vector &v) - { return v.end(); } - -template - inline T* endof (T (&array)[sz]) { return array + sz; } - - -// lengthof -template - inline typename vector::size_type lengthof (vector &v) - { return v.size(); } - -template - inline unsigned int lengthof (T (&)[sz]) { return sz; } - diff --git a/libstdc++-v3/doc/html/24_iterators/howto.html b/libstdc++-v3/doc/html/24_iterators/howto.html deleted file mode 100644 index 7c2f106ac31d..000000000000 --- a/libstdc++-v3/doc/html/24_iterators/howto.html +++ /dev/null @@ -1,200 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 24: Iterators - - - - - - - - - -

Chapter 24: Iterators

- -

Chapter 24 deals with the FORTRAN subroutines for automatically - transforming lemmings into gold. -

- - - -
-

Contents

- - -
- - - -

They ain't pointers!

-

FAQ 5.1 points out that iterators - are not implemented as pointers. They are a generalization of - pointers, but they are implemented in libstdc++ as separate classes. -

-

Keeping that simple fact in mind as you design your code will - prevent a whole lot of difficult-to-understand bugs. -

-

You can think of it the other way 'round, even. Since iterators - are a generalization, that means that pointers are - iterators, and that pointers can be used whenever an - iterator would be. All those functions in the Algorithms chapter - of the Standard will work just as well on plain arrays and their - pointers. -

-

That doesn't mean that when you pass in a pointer, it gets wrapped - into some special delegating iterator-to-pointer class with a layer - of overhead. (If you think that's the case anywhere, you don't - understand templates to begin with...) Oh, no; if you pass - in a pointer, then the compiler will instantiate that template - using T* as a type, and good old high-speed pointer arithmetic as - its operations, so the resulting code will be doing exactly the same - things as it would be doing if you had hand-coded it yourself (for - the 273rd time). -

-

How much overhead is there when using an iterator class? - Very little. Most of the layering classes contain nothing but - typedefs, and typedefs are "meta-information" that simply - tell the compiler some nicknames; they don't create code. That - information gets passed down through inheritance, so while the - compiler has to do work looking up all the names, your runtime code - does not. (This has been a prime concern from the beginning.) -

-

Return to top of page or - 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 - 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: -

-
    -
  1. 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. -
    2. -
  2. 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. -
    3. -
  3. 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. -
    4. -
-

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
-     |                   |
-     |                   |               This is bad.  Always having to
-     |                   |               remember to add or subtract one.
-     |                   |               Off-by-one bugs very common here.
-     V                   V
-        array of N elements
-     |---|---|--...--|---|---|
-     | 0 | 1 |  ...  |N-2|N-1|
-     |---|---|--...--|---|---|
-
-     ^                       ^
-     |                       |
-     |                       |           This is good.  This is safe.  This
-     |                       |           is guaranteed to work.  Just don't
-     |                       |           dereference 'end'.
-   beginning                end
-
-
-

See? Everything between the boundary markers is part of the array. - Simple. -

-

Now think back to your junior-high school algebra course, when you - were learning how to draw graphs. Remember that a graph terminating - with a solid dot meant, "Everything up through this point," - and a graph terminating with an open dot meant, "Everything up - to, but not including, this point," respectively called closed - and open ranges? Remember how closed ranges were written with - brackets, [a,b], and open ranges were written with parentheses, - (a,b)? -

-

The boundary markers for arrays describe a half-open range, - starting with (and including) the first element, and ending with (but - not including) the last element: [beginning,end). See, I - told you it would be simple in the end. -

-

Iterators, and everything working with iterators, follows this same - time-honored tradition. A container's begin() method returns - an iterator referring to the first element, and its end() - method returns a past-the-end iterator, which is guaranteed to be - unique and comparable against any other iterator pointing into the - middle of the container. -

-

Container constructors, container methods, and algorithms, all take - pairs of iterators describing a range of values on which to operate. - All of these ranges are half-open ranges, so you pass the beginning - iterator as the starting parameter, and the one-past-the-end iterator - as the finishing parameter. -

-

This generalizes very well. You can operate on sub-ranges quite - easily this way; functions accepting a [first,last) range - don't know or care whether they are the boundaries of an entire {array, - sequence, container, whatever}, or whether they only enclose a few - elements from the center. This approach also makes zero-length - sequences very simple to recognize: if the two endpoints compare - equal, then the {array, sequence, container, whatever} is empty. -

-

Just don't dereference end(). -

-

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

- - - - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/25_algorithms/howto.html b/libstdc++-v3/doc/html/25_algorithms/howto.html deleted file mode 100644 index bb5caee354ab..000000000000 --- a/libstdc++-v3/doc/html/25_algorithms/howto.html +++ /dev/null @@ -1,116 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 25: Algorithms - - - - - - - - - -

Chapter 25: Algorithms

- -

Chapter 25 deals with the generalized subroutines for automatically - transforming lemmings into gold. -

- - - -
-

Contents

- - -
- - - -

Prerequisites

-

The neatest accomplishment of the algorithms chapter is that all the - work is done via iterators, not containers directly. This means two - important things: -

-
    -
  1. 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. -
    2. -
  2. 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. -
    3. -
-

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 - page will use simple arrays of integers as a playground for - algorithms, just to keep things simple. - The use of N as a size in the - examples is to keep things easy to read but probably won't be valid - code. You can use wrappers such as those described in the - containers chapter to keep - real code readable. -

-

The single thing that trips people up the most is the definition of - range used with iterators; the famous - "past-the-end" rule that everybody loves to hate. The - iterators chapter of this - document has a complete explanation of this simple rule that seems to - cause so much confusion. Once you get range into your head - (it's not that hard, honest!), then the algorithms are a cakewalk. -

-

Return to top of page or - 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 - x.swap(y); instead. -

-

This allows member functions of each container class to take over, and - containers' swap functions should have O(1) complexity according to - the standard. (And while "should" allows implementations to - behave otherwise and remain compliant, this implementation does in - fact use constant-time swaps.) This should not be surprising, since - for two containers of the same type to swap contents, only some - internal pointers to storage need to be exchanged. -

-

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

- - - - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/26_numerics/howto.html b/libstdc++-v3/doc/html/26_numerics/howto.html deleted file mode 100644 index e56659b38043..000000000000 --- a/libstdc++-v3/doc/html/26_numerics/howto.html +++ /dev/null @@ -1,179 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 26: Numerics - - - - - - - - - -

Chapter 26: Numerics

- -

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++, - and overloaded versions for long, float, and - long double have been added for all of them. -

- - -
-

Contents

- - -
- - - -

Complex Number Processing

-

Using complex<> becomes even more comple- er, sorry, - complicated, with the not-quite-gratuitously-incompatible - addition of complex types to the C language. David Tribble has - compiled a list of C++98 and C99 conflict points; his description of - C's new type versus those of C++ and how to get them playing together - nicely is -here. -

-

complex<> is intended to be instantiated with a - floating-point type. As long as you meet that and some other basic - requirements, then the resulting instantiation has all of the usual - math operators defined, as well as definitions of op<< - and op>> that work with iostreams: op<< - prints (u,v) and op>> can read u, - (u), and (u,v). -

-

Return to top of page or - 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 - that C89 is not allowed to make, and neither is C++98. C99 adds a new - keyword, restrict, to apply to individual pointers. The - C++ solution is contained in the library rather than the language - (although many vendors can be expected to add this to their compilers - as an extension). -

-

That library solution is a set of two classes, five template classes, - and "a whole bunch" of functions. The classes are required - to be free of pointer aliasing, so compilers can optimize the - daylights out of them the same way that they have been for FORTRAN. - They are collectively called valarray, although strictly - speaking this is only one of the five template classes, and they are - designed to be familiar to people who have worked with the BLAS - libraries before. -

-

Some more stuff should go here once somebody has time to write it. -

-

Return to top of page or - 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
    • -
-

Here is a simple example of the two forms of accumulate. -

- 
-   int   ar[50];
-   int   someval = somefunction();
-
-   // ...initialize members of ar to something...
-
-   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 - 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, - and multiplies all the members of the array; here we must obviously - use 1 as a starting value instead of 0. -

-

The other three functions have similar dual-signature forms. -

-

Return to top of page or - 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++. -

-

The C99 features depend on the --enable-c99 configure flag. - This flag is already on by default, but it can be disabled by the - user. Also, the configuration machinery will disable it if the - necessary support for C99 (e.g., header files) cannot be found. -

-

As of GCC 3.0, C99 support includes classification functions - such as isnormal, isgreater, - isnan, etc. - The functions used for 'long long' support such as strtoll - are supported, as is the lldiv_t typedef. Also supported - are the wide character functions using 'long long', like - wcstoll. -

-

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

- - - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/27_io/binary_iostreams_kanze.txt b/libstdc++-v3/doc/html/27_io/binary_iostreams_kanze.txt deleted file mode 100644 index 65d79c996c5d..000000000000 --- a/libstdc++-v3/doc/html/27_io/binary_iostreams_kanze.txt +++ /dev/null @@ -1,51 +0,0 @@ - -From: James Kanze -Newsgroups: comp.lang.c++.moderated -Subject: Re: binary iostreams ? -Date: 3 Feb 2001 14:28:19 -0500 -Message-ID: <86lmro86qp.fsf@alex.gabi-soft.de> - -"Plinio Conti" writes: - -|> Why std c++ library stream classes are only text-oriented? - -Because that is the only universally recognized format. - -|> I mean, if I want to write an int, a float, etc. AS IT IS I can't -|> use streams, because they write and read a human readable text -|> format of numbers. - -Correct. - -|> Does anyone know how to solve the problem? - -It depends on what you really want to do. If you are just dumping a -block of memory to disk, in order to free up memory, and will reread it -later in the same run of the same program, ostream::write and -istream::read are what you need. Note, however, that this ony works 1) -in the same run of the same program, and 2) for PODs without pointers. - -If you are writing something that will be read by another program, or a -later run of the same program, you'll have to define a specific format -to use, and implement streams to input and output that. If you are -writing something that will be read by an existing program, or be -transmitted over a network to another machine, you will have to find out -what protocol is expected, and adher to it. - -|> Any public library? - -Not that I know of. I think that there is a library somewhere that -outputs in format RPC, or maybe some Internet format. - -|> What do you think about this choice? - -What other choice is possible? It's not reasonable to ask the standard -to support all binary formats, and it's not reasonable for it to favor -any one of them. Given that, what else can you do. - --- -James Kanze mailto:kanze@gabi-soft.de -Conseils en informatique orientée objet/ - Beratung in objektorientierter Datenverarbeitung -Ziegelhüttenweg 17a, 60598 Frankfurt, Germany Tel. +49(069)63198627 - diff --git a/libstdc++-v3/doc/html/27_io/binary_iostreams_kuehl.txt b/libstdc++-v3/doc/html/27_io/binary_iostreams_kuehl.txt deleted file mode 100644 index 901701ff4805..000000000000 --- a/libstdc++-v3/doc/html/27_io/binary_iostreams_kuehl.txt +++ /dev/null @@ -1,89 +0,0 @@ - -From: kuehl@ramsen.informatik.uni-konstanz.de (Dietmar Kuehl) -Newsgroups: comp.std.c++ -Subject: Re: binary iostreams ? -Date: Sat, 3 Feb 2001 17:17:49 GMT -Message-ID: <95hctq$suu$2@news.BelWue.DE> - -Hi, -Plinio Conti (plinio.contiNO@SPAMMINGmclink.it) wrote: -: Why std c++ library stream classes are only text-oriented? - -There is only a text oriented front end to stream buffers because text -input and output does not vary between platforms. This is very -different for binary output. For example, binary output has to consider - -- word sizes: Is an 'int' two, four, or eight bytes long? The same - questions arise for all other built-in types. - -- what is the bit pattern of a value? I think that at least implicitly - in the standard a binary representation for integer types is required. - I don't think that it is required to use two's complement. In any - case, the floating point representations do differ, eg. in their - number of bytes used. - -- what "endianess" is to be used? - -Basically it is possible to decide a format for each of those. This, -however, implies inefficient implementations on platforms where the -format does not match the internal representation. - -What many people asking for binary I/O forget is that binary I/O also -requires some form of formatting! Assuming that just writing data and -then reading it in will work is asking for problems, eg. when the -compiler version changes and they decided to use a 32 bit integer -rather than a 16 bit integer: It is not even necessary to switch -platforms to run into problems! - -: I mean, if I want to write an int, a float, etc. AS IT IS I can't use -: streams, because they write and read a human readable text format of -: numbers. - -Which is for most I/O a reasonable approach. If it is not for you, you -might want to consider a data base: File I/O is not really useful as a -persistance mechanism. It is fine eg. for user interaction (text I/O), -logging (text I/O), cross platfrom program interaction (formatted I/O), -and data exchange (formatted I/O). In all these cases, the I/O is -formatted, although possible using a binary format. For persistance, -data bases are used. Depending on your needs, a relational or an object -oriented one may be better suited. - -That said, it is worth to mention that it is easy to create a hierarchy -similar to IOStreams built on top of stream buffers but doing binary -formatting. A somewhat aged example is found at -. -This uses XDR formatting of the binary data (well, if I remmeber -correctly, it is easy to plug in a different binary formatting). - -: Does anyone know how to solve the problem? - -Use a data base, text formatting, or binary formatting. With the -details you have given it is impossible to tell which of those is the -right approach because you haven't told *why* you want a binary format -and *what* you want to do. That basically means that you came up with -solution and you want us to confirm that it is the right one without -telling us what problem is solved! Until I have seen the problem I -doubt that binary I/O is the right approach... - -... and, BTW, using 'std::istream::read()' and 'std::ostream::write()' -is almost certainly the *wrong* approach! These functions are an -historical mistake which should have been corrected in the standard: -It is my understanding that these methods were present in the IOStream -version predating the rework from Jerry Schwartz and were left in to -be compatible with the earlier stuff although they were not necessary: -You could get binary I/O from the stream buffer level. The original -IOStream library (maybe you remember using ) did not have -stream buffers and thus basic support for binary I/O was also present -on the streams level. - -: What do you think about this choice? - -When I wrote the above paragraph about confirming your choice, I haven't -read this question! As I said above: You told us what solution you have -choosen without stating what problem is solved. We cannot determine -whether your choice is the right one. Actually, I'm pretty sure it is -the wrong one but without seen the details I can't be certain. --- - -Phaidros eaSE - Easy Software Engineering: - diff --git a/libstdc++-v3/doc/html/27_io/howto.html b/libstdc++-v3/doc/html/27_io/howto.html deleted file mode 100644 index 46d03b34630e..000000000000 --- a/libstdc++-v3/doc/html/27_io/howto.html +++ /dev/null @@ -1,779 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Chapter 27: Input/Output - - - - - - - - - -

Chapter 27: Input/Output

- -

Chapter 27 deals with iostreams and all their subcomponents - and extensions. All kinds of fun stuff. -

- - - -
-

Contents

- - -
- - - -

Copying a file

-

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 - (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 - 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 - handled by the basic_streambuf family. Fortunately, the - operator<< is overloaded to take an ostream and - a pointer-to-streambuf, in order to help with just this kind of - "dump the data verbatim" situation. -

-

Why a pointer to streambuf and not just a streambuf? Well, - the [io]streams hold pointers (or references, depending on the - implementation) to their buffers, not the actual - buffers. This allows polymorphic behavior on the part of the buffers - 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();
-

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 - extraction process removes all the whitespace, leaving you with no - blank lines and only "Thequickbrownfox...". With - libraries that do not define that operator, IN (or one of IN's - member pointers) sometimes gets converted to a void*, and the output - file then contains a perfect text representation of a hexadecimal - address (quite a big surprise). Others don't compile at all. -

-

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

-

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

- -
-

The buffering is screwing up my program!

- -

First, are you sure that you understand buffering? Particularly - the fact that C++ may not, in fact, have anything to do with it? -

-

The rules for buffering can be a little odd, but they aren't any - different from those of C. (Maybe that's why they can be a bit - odd.) Many people think that writing a newline to an output - stream automatically flushes the output buffer. This is true only - when the output stream is, in fact, a terminal and not a file - or some other device -- and that may not even be true - since C++ says nothing about files nor terminals. All of that is - system-dependent. (The "newline-buffer-flushing only occurring - on terminals" thing is mostly true on Unix systems, though.) -

-

Some people also believe that sending endl down an - output stream only writes a newline. This is incorrect; after a - newline is written, the buffer is also flushed. Perhaps this - is the effect you want when writing to a screen -- get the text - out as soon as possible, etc -- but the buffering is largely - wasted when doing this to a file: -

- 
-   output << "a line of text" << endl;
-   output << some_data_variable << endl;
-   output << "another line of text" << endl;
-

The proper thing to do in this case to just write the data out - and let the libraries and the system worry about the buffering. - If you need a newline, just write a newline: -

- 
-   output << "a line of text\n"
-          << some_data_variable << '\n'
-          << "another line of text\n";
-

I have also joined the output statements into a single statement. - You could make the code prettier by moving the single newline to - the start of the quoted text on the last line, for example. -

-

If you do need to flush the buffer above, you can send an - endl if you also need a newline, or just flush the buffer - yourself: -

- 
-   output << ...... << flush;    // can use std::flush manipulator
-   output.flush();               // or call a member fn
-

On the other hand, there are times when writing to a file should - be like writing to standard error; no buffering should be done - because the data needs to appear quickly (a prime example is a - log file for security-related information). The way to do this is - just to turn off the buffering before any I/O operations at - all have been done (note that opening counts as an I/O operation): -

- 
-   std::ofstream    os;
-   std::ifstream    is;
-   int   i;
-
-   os.rdbuf()->pubsetbuf(0,0);
-   is.rdbuf()->pubsetbuf(0,0);
-
-   os.open("/foo/bar/baz");
-   is.open("/qux/quux/quuux");
-   ...
-   os << "this data is written immediately\n";
-   is >> i;   // and this will probably cause a disk read
-

Since all aspects of buffering are handled by a streambuf-derived - member, it is necessary to get at that member with rdbuf(). - Then the public version of setbuf can be called. The - arguments are the same as those for the Standard C I/O Library - function (a buffer area followed by its size). -

-

A great deal of this is implementation-dependent. For example, - streambuf does not specify any actions for its own - setbuf()-ish functions; the classes derived from - streambuf each define behavior that "makes - sense" for that class: an argument of (0,0) turns off buffering - for filebuf but does nothing at all for its siblings - stringbuf and strstreambuf, and specifying - anything other than (0,0) has varying effects. - User-defined classes derived from streambuf can - do whatever they want. (For filebuf and arguments for - (p,s) other than zeros, libstdc++ does what you'd expect: - the first s bytes of p are used as a buffer, - which you must allocate and deallocate.) -

-

A last reminder: there are usually more buffers involved than - just those at the language/library level. Kernel buffers, disk - buffers, and the like will also have an effect. Inspecting and - changing those are system-dependent. -

-

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

- -
-

Binary I/O

-

The first and most important thing to remember about binary I/O is - that opening a file with ios::binary is not, repeat - not, the only thing you have to do. It is not a silver - bullet, and will not allow you to use the <</>> - operators of the normal fstreams to do binary I/O. -

-

Sorry. Them's the breaks. -

-

This isn't going to try and be a complete tutorial on reading and - writing binary files (because "binary" - covers a lot of ground), but we will try and clear - up a couple of misconceptions and common errors. -

-

First, ios::binary has exactly one defined effect, no more - and no less. Normal text mode has to be concerned with the newline - characters, and the runtime system will translate between (for - example) '\n' and the appropriate end-of-line sequence (LF on Unix, - CRLF on DOS, CR on Macintosh, etc). (There are other things that - normal mode does, but that's the most obvious.) Opening a file in - binary mode disables this conversion, so reading a CRLF sequence - under Windows won't accidentally get mapped to a '\n' character, etc. - Binary mode is not supposed to suddenly give you a bitstream, and - if it is doing so in your program then you've discovered a bug in - your vendor's compiler (or some other part of the C++ implementation, - possibly the runtime system). -

-

Second, using << to write and >> to - read isn't going to work with the standard file stream classes, even - if you use skipws during reading. Why not? Because - ifstream and ofstream exist for the purpose of formatting, - not reading and writing. Their job is to interpret the data into - text characters, and that's exactly what you don't want to happen - during binary I/O. -

-

Third, using the get() and put()/write() member - functions still aren't guaranteed to help you. These are - "unformatted" I/O functions, but still character-based. - (This may or may not be what you want, see below.) -

-

Notice how all the problems here are due to the inappropriate use - of formatting functions and classes to perform something - which requires that formatting not be done? There are a - seemingly infinite number of solutions, and a few are listed here: -

-
    -
  • "Derive your own fstream-type classes and write your own - <</>> operators to do binary I/O on whatever data - types you're using." This is a Bad Thing, because while - the compiler would probably be just fine with it, other humans - are going to be confused. The overloaded bitshift operators - have a well-defined meaning (formatting), and this breaks it. -
    • -
  • "Build the file structure in memory, then mmap() - the file and copy the structure." Well, this is easy to - make work, and easy to break, and is pretty equivalent to - using ::read() and ::write() directly, and - makes no use of the iostream library at all... -
    • -
  • "Use streambufs, that's what they're there for." - While not trivial for the beginner, this is the best of all - solutions. The streambuf/filebuf layer is the layer that is - responsible for actual I/O. If you want to use the C++ - library for binary I/O, this is where you start. -
    • -
-

How to go about using streambufs is a bit beyond the scope of this - document (at least for now), but while streambufs go a long way, - they still leave a couple of things up to you, the programmer. - As an example, byte ordering is completely between you and the - operating system, and you have to handle it yourself. -

-

Deriving a streambuf or filebuf - class from the standard ones, one that is specific to your data - types (or an abstraction thereof) is probably a good idea, and - lots of examples exist in journals and on Usenet. Using the - standard filebufs directly (either by declaring your own or by - using the pointer returned from an fstream's rdbuf()) - is certainly feasible as well. -

-

One area that causes problems is trying to do bit-by-bit operations - with filebufs. C++ is no different from C in this respect: I/O - must be done at the byte level. If you're trying to read or write - a few bits at a time, you're going about it the wrong way. You - must read/write an integral number of bytes and then process the - bytes. (For example, the streambuf functions take and return - variables of type int_type.) -

-

Another area of problems is opening text files in binary mode. - Generally, binary mode is intended for binary files, and opening - text files in binary mode means that you now have to deal with all of - those end-of-line and end-of-file problems that we mentioned before. - An instructive thread from comp.lang.c++.moderated delved off into - this topic starting more or less at - this - article and continuing to the end of the thread. (You'll have to - sort through some flames every couple of paragraphs, but the points - made are good ones.) -

- -
-

What is this <sstream>/stringstreams thing?

-

Stringstreams (defined in the header <sstream>) - are in this author's opinion one of the coolest things since - sliced time. An example of their use is in the Received Wisdom - section for Chapter 21 (Strings), - describing how to - format strings. -

-

The quick definition is: they are siblings of ifstream and ofstream, - and they do for std::string what their siblings do for - files. All that work you put into writing << and - >> functions for your classes now pays off - again! Need to format a string before passing the string - to a function? Send your stuff via << to an - ostringstream. You've read a string as input and need to parse it? - Initialize an istringstream with that string, and then pull pieces - out of it with >>. Have a stringstream and need to - get a copy of the string inside? Just call the str() - member function. -

-

This only works if you've written your - <</>> functions correctly, though, - and correctly means that they take istreams and ostreams as - parameters, not ifstreams and ofstreams. If they - take the latter, then your I/O operators will work fine with - file streams, but with nothing else -- including stringstreams. -

-

If you are a user of the strstream classes, you need to update - your code. You don't have to explicitly append ends to - terminate the C-style character array, you don't have to mess with - "freezing" functions, and you don't have to manage the - memory yourself. The strstreams have been officially deprecated, - which means that 1) future revisions of the C++ Standard won't - support them, and 2) if you use them, people will laugh at you. -

- -
-

Deriving a stream buffer

-

Creating your own stream buffers for I/O can be remarkably easy. - If you are interested in doing so, we highly recommend two very - excellent books: - Standard C++ - IOStreams and Locales by Langer and Kreft, ISBN 0-201-18395-1, and - The C++ Standard Library - by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by - Addison-Wesley, who isn't paying us a cent for saying that, honest. -

-

Here is a simple example, io/outbuf1, from the Josuttis text. It - transforms everything sent through it to uppercase. This version - assumes many things about the nature of the character type being - used (for more information, read the books or the newsgroups): -

- 
-    #include <iostream>
-    #include <streambuf>
-    #include <locale>
-    #include <cstdio>
-
-    class outbuf : public std::streambuf
-    {
-      protected:
-	/* central output function
-	 * - print characters in uppercase mode
-	 */
-	virtual int_type overflow (int_type c) {
-	    if (c != EOF) {
-		// convert lowercase to uppercase
-		c = std::toupper(static_cast<char>(c),getloc());
-
-		// and write the character to the standard output
-		if (putchar(c) == EOF) {
-		    return EOF;
-		}
-	    }
-	    return c;
-	}
-    };
-
-    int main()
-    {
-	// create special output buffer
-	outbuf ob;
-	// initialize output stream with that output buffer
-	std::ostream out(&ob);
-
-	out << "31 hexadecimal: "
-	    << std::hex << 31 << std::endl;
-	return 0;
-    }
-
-

Try it yourself! More examples can be found in 3.1.x code, in - include/ext/*_filebuf.h, and on - Dietmar - Kühl's IOStreams page. -

- -
-

More on binary I/O

-

Towards the beginning of February 2001, the subject of - "binary" I/O was brought up in a couple of places at the - same time. One notable place was Usenet, where James Kanze and - Dietmar Kühl separately posted articles on why attempting - generic binary I/O was not a good idea. (Here are copies of - Kanze's article and - Kühl's article.) -

-

Briefly, the problems of byte ordering and type sizes mean that - the unformatted functions like ostream::put() and - istream::get() cannot safely be used to communicate - between arbitrary programs, or across a network, or from one - invocation of a program to another invocation of the same program - on a different platform, etc. -

-

The entire Usenet thread is instructive, and took place under the - subject heading "binary iostreams" on both comp.std.c++ - and comp.lang.c++.moderated in parallel. Also in that thread, - Dietmar Kühl mentioned that he had written a pair of stream - classes that would read and write XDR, which is a good step towards - a portable binary format. -

- -
-

Pathetic performance? Ditch C.

-

It sounds like a flame on C, but it isn't. Really. Calm down. - I'm just saying it to get your attention. -

-

Because the C++ library includes the C library, both C-style and - C++-style I/O have to work at the same time. For example: -

- 
-     #include <iostream>
-     #include <cstdio>
-
-     std::cout << "Hel";
-     std::printf ("lo, worl");
-     std::cout << "d!\n";
-
-

This must do what you think it does. -

-

Alert members of the audience will immediately notice that buffering - is going to make a hash of the output unless special steps are taken. -

-

The special steps taken by libstdc++, at least for version 3.0, - involve doing very little buffering for the standard streams, leaving - most of the buffering to the underlying C library. (This kind of - thing is tricky to get right.) - The upside is that correctness is ensured. The downside is that - writing through cout can quite easily lead to awful - performance when the C++ I/O library is layered on top of the C I/O - library (as it is for 3.0 by default). Some patches have been applied - which improve the situation for 3.1. -

-

However, the C and C++ standard streams only need to be kept in sync - when both libraries' facilities are in use. If your program only uses - C++ I/O, then there's no need to sync with the C streams. The right - thing to do in this case is to call -

- 
-     #include any of the I/O headers such as ios, iostream, etc
-
-     std::ios::sync_with_stdio(false);
-
-

You must do this before performing any I/O via the C++ stream objects. - Once you call this, the C++ streams will operate independently of the - (unused) C streams. For GCC 3.x, this means that cout and - company will become fully buffered on their own. -

-

Note, by the way, that the synchronization requirement only applies to - the standard streams (cin, cout, - cerr, - clog, and their wide-character counterparts). File stream - objects that you declare yourself have no such requirement and are fully - buffered. -

- -
-

Threads and I/O

-

I'll assume that you have already read the - general notes on library threads, - and the - notes on threaded container - access (you might not think of an I/O stream as a container, but - the points made there also hold here). If you have not read them, - please do so first. -

-

This gets a bit tricky. Please read carefully, and bear with me. -

-

Structure

-

A wrapper - type called __basic_file provides our abstraction layer - for the std::filebuf classes. Nearly all decisions dealing - with actual input and output must be made in __basic_file. -

-

A generic locking mechanism is somewhat in place at the filebuf layer, - but is not used in the current code. Providing locking at any higher - level is akin to providing locking within containers, and is not done - for the same reasons (see the links above). -

-

The defaults for 3.0.x

-

The __basic_file type is simply a collection of small wrappers around - the C stdio layer (again, see the link under Structure). We do no - locking ourselves, but simply pass through to calls to fopen, - fwrite, and so forth. -

-

So, for 3.0, the question of "is multithreading safe for I/O" - must be answered with, "is your platform's C library threadsafe - for I/O?" Some are by default, some are not; many offer multiple - implementations of the C library with varying tradeoffs of threadsafety - and efficiency. You, the programmer, are always required to take care - with multiple threads. -

-

(As an example, the POSIX standard requires that C stdio FILE* - operations are atomic. POSIX-conforming C libraries (e.g, on Solaris - and GNU/Linux) have an internal mutex to serialize operations on - FILE*s. However, you still need to not do stupid things like calling - fclose(fs) in one thread followed by an access of - fs in another.) -

-

So, if your platform's C library is threadsafe, then your - fstream I/O operations will be threadsafe at the lowest - level. For higher-level operations, such as manipulating the data - contained in the stream formatting classes (e.g., setting up callbacks - inside an std::ofstream), you need to guard such accesses - like any other critical shared resource. -

-

The future

-

A - second choice may be available for I/O implementations: libio. This is - disabled by default, and in fact will not currently work due to other - issues. It will be revisited, however. -

-

The libio code is a subset of the guts of the GNU libc (glibc) I/O - implementation. When libio is in use, the __basic_file - type is basically derived from FILE. (The real situation is more - complex than that... it's derived from an internal type used to - implement FILE. See libio/libioP.h to see scary things done with - vtbls.) The result is that there is no "layer" of C stdio - to go through; the filebuf makes calls directly into the same - functions used to implement fread, fwrite, - and so forth, using internal data structures. (And when I say - "makes calls directly," I mean the function is literally - replaced by a jump into an internal function. Fast but frightening. - *grin*) -

-

Also, the libio internal locks are used. This requires pulling in - large chunks of glibc, such as a pthreads implementation, and is one - of the issues preventing widespread use of libio as the libstdc++ - cstdio implementation. -

-

But we plan to make this work, at least as an option if not a future - default. Platforms running a copy of glibc with a recent-enough - version will see calls from libstdc++ directly into the glibc already - installed. For other platforms, a copy of the libio subsection will - be built and included in libstdc++. -

-

Alternatives

-

Don't forget that other cstdio implementations are possible. You could - easily write one to perform your own forms of locking, to solve your - "interesting" problems. -

- -
-

Which header?

-

To minimize the time you have to wait on the compiler, it's good to - only include the headers you really need. Many people simply include - <iostream> when they don't need to -- and that can penalize - your runtime as well. Here are some tips on which header to use - for which situations, starting with the simplest. -

-

<iosfwd> should be included whenever you simply - need the name of an I/O-related class, such as - "ofstream" or "basic_streambuf". Like the name - implies, these are forward declarations. (A word to all you fellow - old school programmers: trying to forward declare classes like - "class istream;" won't work. Look in the iosfwd header if - you'd like to know why.) For example, -

- 
-    #include <iosfwd>
-
-    class MyClass
-    {
-        ....
-        std::ifstream&   input_file;
-    };
-
-    extern std::ostream& operator<< (std::ostream&, MyClass&);
-
-

<ios> declares the base classes for the entire - I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the - counting types std::streamoff and std::streamsize, the file - positioning type std::fpos, and the various manipulators like - std::hex, std::fixed, std::noshowbase, and so forth. -

-

The ios_base class is what holds the format flags, the state flags, - and the functions which change them (setf(), width(), precision(), - etc). You can also store extra data and register callback functions - through ios_base, but that has been historically underused. Anything - which doesn't depend on the type of characters stored is consolidated - here. -

-

The template class basic_ios is the highest template class in the - hierarchy; it is the first one depending on the character type, and - holds all general state associated with that type: the pointer to the - polymorphic stream buffer, the facet information, etc. -

-

<streambuf> declares the template class - basic_streambuf, and two standard instantiations, streambuf and - wstreambuf. If you need to work with the vastly useful and capable - stream buffer classes, e.g., to create a new form of storage - transport, this header is the one to include. -

-

<istream>/<ostream> are - the headers to include when you are using the >>/<< - interface, or any of the other abstract stream formatting functions. - For example, -

- 
-    #include <istream>
-
-    std::ostream& operator<< (std::ostream& os, MyClass& c)
-    {
-       return os << c.data1() << c.data2();
-    }
-
-

The std::istream and std::ostream classes are the abstract parents of - the various concrete implementations. If you are only using the - interfaces, then you only need to use the appropriate interface header. -

-

<iomanip> provides "extractors and inserters - that alter information maintained by class ios_base and its derived - classes," such as std::setprecision and std::setw. If you need - to write expressions like os << setw(3); or - is >> setbase(8);, you must include <iomanip>. -

-

<sstream>/<fstream> - declare the six stringstream and fstream classes. As they are the - standard concrete descendants of istream and ostream, you will already - know about them. -

-

Finally, <iostream> provides the eight standard - global objects (cin, cout, etc). To do this correctly, this header - also provides the contents of the <istream> and <ostream> - headers, but nothing else. The contents of this header look like -

- 
-    #include <ostream>
-    #include <istream>
-
-    namespace std
-    {
-        extern istream cin;
-        extern ostream cout;
-        ....
-
-        // this is explained below
-        static ios_base::Init __foo;    // not its real name
-    }
-
-

Now, the runtime penalty mentioned previously: the global objects - must be initialized before any of your own code uses them; this is - guaranteed by the standard. Like any other global object, they must - be initialized once and only once. This is typically done with a - construct like the one above, and the nested class ios_base::Init is - specified in the standard for just this reason. -

-

How does it work? Because the header is included before any of your - code, the __foo object is constructed before any of - your objects. (Global objects are built in the order in which they - are declared, and destroyed in reverse order.) The first time the - constructor runs, the eight stream objects are set up. -

-

The static keyword means that each object file compiled - from a source file containing <iostream> will have its own - private copy of __foo. There is no specified order - of construction across object files (it's one of those pesky NP - problems that make life so interesting), so one copy in each object - file means that the stream objects are guaranteed to be set up before - any of your code which uses them could run, thereby meeting the - requirements of the standard. -

-

The penalty, of course, is that after the first copy of - __foo is constructed, all the others are just wasted - processor time. The time spent is merely for an increment-and-test - inside a function call, but over several dozen or hundreds of object - files, that time can add up. (It's not in a tight loop, either.) -

-

The lesson? Only include <iostream> when you need to use one of - the standard objects in that source file; you'll pay less startup - time. Only include the header files you need to in general; your - compile times will go down when there's less parsing work to do. -

- - -
-

Using FILE*s and file descriptors with IOStreams

- -

The v2 library included non-standard extensions to construct - std::filebufs from C stdio types such as - FILE*s and POSIX file descriptors. - Today the recommended way to use stdio types with libstdc++ - IOStreams is via the stdio_filebuf class (see below), - but earlier releases provided slightly different mechanisms. -

-
    -
  • 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 - descriptors can be used for on your platform. Naturally, the - 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. - This class can be constructed from a C FILE* or a file - descriptor, and provides the fd() function. -
    • -
-

If you want to access a filebuf's file descriptor to - implement file locking (e.g. using the fcntl() system - call) then you might be interested in Henry Suter's - RWLock - class. -

- - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - - - diff --git a/libstdc++-v3/doc/html/README b/libstdc++-v3/doc/html/README new file mode 100644 index 000000000000..ea5dcfcdd41d --- /dev/null +++ b/libstdc++-v3/doc/html/README @@ -0,0 +1,3 @@ +The HTML documentation in this folder is generated from the XML sources. + +To change or edit, please edit the XML sources in the ../xml directory. diff --git a/libstdc++-v3/doc/html/configopts.html b/libstdc++-v3/doc/html/configopts.html deleted file mode 100644 index c830a9967ba7..000000000000 --- a/libstdc++-v3/doc/html/configopts.html +++ /dev/null @@ -1,342 +0,0 @@ - - - - - - - - - - libstdc++ configure options - - - - - -

Interesting configure -options

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html. -

- -

- To the libstdc++ homepage. -

- - -
-

Here are some of the non-obvious options to libstdc++'s configure. - Keep in mind that - - they - all have opposite forms as well - (enable/disable and with/without). The defaults are for current - development sources, which may be different than those for - released versions. -

-

The canonical way to find out the configure options that are - available for a given set of libstdc++ sources is to go to the - source directory and then type: ./configure --help -

- -
-
--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-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. This option can - change the library ABI. -

-
- -
--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}) - instead of ${libdir}. This option is useful if you - intend to use several versions of gcc in parallel. In addition, - libstdc++'s include files will be installed in - ${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++, - unless you also specify - --with-gxx-include-dir=dirname during configuration. -

-
- -
--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 - "c++/(version)". -

- 
-   --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008
- -
--enable-cstdio
-

This is an abbreviated form of '--enable-cstdio=stdio' - (described next). This option can change the library ABI. -

-
- -
--enable-cstdio=OPTION
-

Select a target-specific I/O package. At the moment, the only - choice is to use 'stdio', a generic "C" abstraction. - The default is 'stdio'. -

-
- -
--enable-clocale
-

This is an abbreviated form of '--enable-clocale=generic' - (described next). This option can change the library ABI. -

-
- -
--enable-clocale=OPTION
-

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

- -

As part of the configuration process, the "C" library is - probed both for sufficient vintage, and installed locale - data. If either of these elements are not present, the C++ - locale model default to 'generic.' On glibc-based systems of - version 2.2.5 and above with installed locale files, 'gnu' is - automatically selected. -

-
- -
--enable-libstdcxx-allocator
-

This is an abbreviated form of - '--enable-libstdcxx-allocator=auto' (described - next). This option can change the library ABI. -

-
- -
--enable-libstdcxx-allocator=OPTION
-

Select a target-specific underlying std::allocator. The - choices are 'new' to specify a wrapper for new, 'malloc' to - specify a wrapper for malloc, 'mt' for a fixed power of two allocator - (documented under extensions), - 'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator. - This option can change the library ABI. -

-
- -
--enable-cheaders=OPTION
-

This allows the user to define the approach taken for C header - compatibility with C++. Options are c, c_std, and c_global. - These correspond to the source directory's include/c, - include/c_std, and include/c_global, and may also include - include/c_compatibility. The default is c_global. -

-
- -
--enable-threads
-

This is an abbreviated form of '--enable-threads=yes' - (described next). This option can change the library ABI. -

-
- -
--enable-threads=OPTION
-

Select a threading library. A full description is given in the - general compiler - configuration instructions. -

-
- -
--enable-libstdcxx-debug
-

Build separate debug libraries in addition to what is normally built. - By default, the debug libraries are compiled with - CXXFLAGS='-g3 -O0' - , are installed in ${libdir}/debug, and have the - same names and versioning information as the non-debug - libraries. This option is off by default. -

-

Note this make command, executed in - the build directory, will do much the same thing, without the - configuration difference and without building everything twice: - make CXXFLAGS='-g3 -O0' all -

-
- -
--enable-libstdcxx-debug-flags=FLAGS
- -

This option is only valid when --enable-debug - is also specified, and applies to the debug builds only. With - this option, you can pass a specific string of flags to the - compiler to use when building the debug versions of libstdc++. - FLAGS is a quoted string of options, like -

- 
-  --enable-libstdcxx-debug-flags='-g3 -O1 -gdwarf-2'
-
- -
--enable-cxx-flags=FLAGS
-

With this option, you can pass a string of -f (functionality) - flags to the compiler to use when building libstdc++. This - option can change the library ABI. FLAGS is a quoted string of - options, like -

- 
-  --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'
-

- Note that the flags don't necessarily have to all be -f flags, - as shown, but usually those are the ones that will make sense - for experimentation and configure-time overriding. -

-

The advantage of --enable-cxx-flags over setting CXXFLAGS in - the 'make' environment is that, if files are automatically - rebuilt, the same flags will be used when compiling those files - as well, so that everything matches. -

-

Fun flags to try might include combinations of -

- 
-  -fstrict-aliasing
-  -fno-exceptions
-  -ffunction-sections
-  -fvtable-gc
-

and opposite forms (-fno-) of the same. Tell us (the libstdc++ - mailing list) if you discover more! -

-
- -
--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 - specified by the C++ standard will be put into namespace - __gnu_cxx, and then all these names will - be injected into namespace std, so that C99 functions can be - used "as if" they were in the C++ standard (as they - will eventually be in some future revision of the standard, - without a doubt). By default, C99 support is on, assuming the - configure probes find all the necessary functions and bits - necessary. This option can change the library ABI. -

-
- -
--enable-wchar_t [default]
-

Template specializations for the "wchar_t" type are - required for wide character conversion support. Disabling - wide character specializations may be expedient for initial - porting efforts, but builds only a subset of what is required by - ISO, and is not recommended. By default, this option is on. - This option can change the library ABI. -

-
- -
--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 - templates and the like for iostreams). This option is on by default: - if enabled, users will have to either use the new-style "C" - headers by default (i.e., <cmath> not <math.h>) - or add appropriate compile-time flags to all compile lines to - allow "C" visibility of this feature (on GNU/Linux, - the flag is -D_ISOC99_SOURCE, which is added automatically via - CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). - This option can change the library ABI. -

-
- -
--enable-fully-dynamic-string
-

This option enables a special version of basic_string avoiding - the optimization that allocates empty objects in static memory. - Mostly useful together with shared memory allocators, see PR - libstdc++/16612 for details. -

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

In 3.1 and later, tries to turn on symbol versioning in the - shared library (if a shared library has been - requested). Values for 'style' that are currently supported - are 'gnu', 'gnu-versioned-namespace', 'darwin', and - 'darwin-export'. Both gnu- options require that a recent - version of the GNU linker be in use. Both darwin options are - equivalent. With no style given, the configure script will try - to guess correct defaults for the host system, probe to see if - additional requirements are necessary and present for - activation, and if so, will turn symbol versioning on. This - option can change the library ABI. -

- -
- -
--enable-visibility
-

In 4.2 and later, enables or disables visibility attributes. - If enabled (as by default), and the compiler seems capable of - passing the simple sanity checks thrown at it, adjusts items - in namespace std, namespace std::tr1, and namespace __gnu_cxx - so that -fvisibility options work. -

-
- -
--enable-libstdcxx-pch
-

In 3.4 and later, tries to turn on the generation of - stdc++.h.gch, a pre-compiled file including all the standard - C++ includes. If enabled (as by default), and the compiler - seems capable of passing the simple sanity checks thrown at - it, try to build stdc++.h.gch as part of the make process. - In addition, this generated file is used later on (by appending - --include bits/stdc++.h to CXXFLAGS) when running the - testsuite. -

-
- -
--disable-hosted-libstdcxx
-

By default, a complete hosted C++ library is built. The - C++ Standard also describes a freestanding environment, - in which only a minimal set of headers are provided. This option - builds such an environment. -

-
-
-

Return to the top of the page or - to the libstdc++ homepage. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/debug.html b/libstdc++-v3/doc/html/debug.html deleted file mode 100644 index 61c6a8ba17b9..000000000000 --- a/libstdc++-v3/doc/html/debug.html +++ /dev/null @@ -1,474 +0,0 @@ - - - - - - - - - - Debugging schemes and strategies - - - - - -

Debugging schemes and strategies

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/debug.html. -

- -

- To the libstdc++ homepage. -

- - -
-

There are numerous things that can be done to improve the ease with - which C++ binaries are debugged when using the GNU - tool chain. Here are some of them. -

- -

Compiler flags determine debug info

-

The default optimizations and debug flags for a libstdc++ build are - -g -O2. However, both debug and optimization flags can - be varied to change debugging characteristics. For instance, - turning off all optimization via the -g -O0 flag will - disable inlining, so that stepping through all functions, including - inlined constructors and destructors, is possible. In addition, - -fno-eliminate-unused-debug-types can be used when - additional debug information, such as nested class info, is desired. -

- -

Or, the debug format that the compiler and debugger use to communicate - information about source constructs can be changed via - -gdwarf-2 or -gstabs flags: some debugging - formats permit more expressive type and scope information to be - shown in gdb. The default debug information for a particular - platform can be identified via the value set by the - PREFERRED_DEBUGGING_TYPE macro in the gcc sources. -

- -

Many other options are available: please see -"Options for Debugging Your Program" - in Using the GNU Compiler Collection (GCC) for a complete list. -

- -

Using special flags to make a debug binary

-

If you would like debug symbols in libstdc++, there are two ways to - build libstdc++ with debug flags. The first is to run make from the - toplevel in a freshly-configured tree with -

-
-     --enable-libstdcxx-debug
-
-

and perhaps

-
-     --enable-libstdcxx-debug-flags='...'
-
-

to create a separate debug build. Both the normal build and the - debug build will persist, without having to specify - CXXFLAGS, and the debug library will be installed in a - separate directory tree, in (prefix)/lib/debug. For - more information, look at the configuration - options document. -

- -

A second approach is to use the configuration flags -

-
-     make CXXFLAGS='-g3 -O0' all
-
- -

This quick and dirty approach is often sufficient for quick - debugging tasks, when you cannot or don't want to recompile your - application to use the debug mode.

- -

The libstdc++ debug mode

-

By default, libstdc++ is built with efficiency in mind, and - therefore performs little or no error checking that is not required - by the C++ standard. This means that programs that incorrectly use - the C++ standard library will exhibit behavior that is not portable - and may not even be predictable, because they tread into - implementation-specific or undefined behavior. To detect some of - these errors before they can become problematic, libstdc++ offers a - debug mode that provides additional checking of library facilities, - and will report errors in the use of libstdc++ as soon as they can - be detected by emitting a description of the problem to standard - error and aborting the program. This debug mode is available with - GCC 3.4.0 and later versions.

- -

The libstdc++ debug mode performs checking for many areas of the C++ - standard, but the focus is on checking interactions among standard - iterators, containers, and algorithms, including:

- -
    -
  • Safe iterators: Iterators keep track of the - container whose elements they reference, so errors such as - incrementing a past-the-end iterator or dereferencing an iterator - that points to a container that has been destructed are diagnosed - immediately.
    • - -
  • Algorithm preconditions: Algorithms attempt to - validate their input parameters to detect errors as early as - possible. For instance, the set_intersection - algorithm requires that its iterator - parameters first1 and last1 form a valid - iterator range, and that the sequence - [first1, last1) is sorted according to - the same predicate that was passed - to set_intersection; the libstdc++ debug mode will - detect an error if the sequence is not sorted or was sorted by a - different predicate.
    • -
- -

Using the libstdc++ debug mode

-

To use the libstdc++ debug mode, compile your application with the - compiler flag -D_GLIBCXX_DEBUG. Note that this flag - changes the sizes and behavior of standard class templates such - as std::vector, and therefore you can only link code - compiled with debug mode and code compiled without debug mode if no - instantiation of a container is passed between the two translation - units.

- -

By default, error messages are formatted to fit on lines of about - 78 characters. The environment variable - GLIBCXX_DEBUG_MESSAGE_LENGTH can be used to request a - different length.

- -

For information about the design of the libstdc++ debug mode, - please see the libstdc++ debug mode design - document.

- -

Using the debugging containers without debug - mode

-

When it is not feasible to recompile your entire application, or - only specific containers need checking, debugging containers are - available as GNU extensions. These debugging containers are - functionally equivalent to the standard drop-in containers used in - debug mode, but they are available in a separate namespace as GNU - extensions and may be used in programs compiled with either release - mode or with debug mode. The - following table provides the names and headers of the debugging - containers: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ContainerHeaderDebug containerDebug header
std::bitset<bitset>__gnu_debug::bitset<debug/bitset>
std::deque<deque>__gnu_debug::deque<debug/deque>
std::list<list>__gnu_debug::list<debug/list>
std::map<map>__gnu_debug::map<debug/map>
std::multimap<map>__gnu_debug::multimap<debug/map>
std::multiset<set>__gnu_debug::multiset<debug/set>
std::set<set>__gnu_debug::set<debug/set>
std::string<string>__gnu_debug::string<debug/string>
std::wstring<string>__gnu_debug::wstring<debug/string>
std::basic_string<string>__gnu_debug::basic_string<debug/string>
std::vector<vector>__gnu_debug::vector<debug/vector>
- -

In addition, when compiling in C++0x mode, these additional -containers have additional debug capability. -

- - - - - - - - - - - - - - - - - - - - - - - - - - -
std::unordered_map<unordered_map>__gnu_debug::unordered_map<debug/unordered_map>
std::unordered_multimap<unordered_map>__gnu_debug::unordered_multimap<debug/unordered_map>
std::unordered_set<unordered_set>__gnu_debug::unordered_set<debug/unordered_set>
std::unordered_multiset<unordered_set>__gnu_debug::unordered_multiset<debug/unordered_set>
- -

Debug mode semantics

-

A program that uses the C++ standard library correctly - will maintain the same semantics under debug mode as it had with - the normal (release) library. All functional and exception-handling - guarantees made by the normal library also hold for the debug mode - library, with one exception: performance guarantees made by the - normal library may not hold in the debug mode library. For - instance, erasing an element in a std::list is a - constant-time operation in normal library, but in debug mode it is - linear in the number of iterators that reference that particular - list. So while your (correct) program won't change its results, it - is likely to execute more slowly.

- -

libstdc++ includes many extensions to the C++ standard library. In - some cases the extensions are obvious, such as the hashed - associative containers, whereas other extensions give predictable - results to behavior that would otherwise be undefined, such as - throwing an exception when a std::basic_string is - constructed from a NULL character pointer. This latter category also - includes implementation-defined and unspecified semantics, such as - the growth rate of a vector. Use of these extensions is not - considered incorrect, so code that relies on them will not be - rejected by debug mode. However, use of these extensions may affect - the portability of code to other implementations of the C++ standard - library, and is therefore somewhat hazardous. For this reason, the - libstdc++ debug mode offers a "pedantic" mode (similar to - GCC's -pedantic compiler flag) that attempts to emulate - the semantics guaranteed by the C++ standard. For - instance, constructing a std::basic_string with a NULL - character pointer would result in an exception under normal mode or - non-pedantic debug mode (this is a libstdc++ extension), whereas - under pedantic debug mode libstdc++ would signal an error. To enable - the pedantic debug mode, compile your program with - both -D_GLIBCXX_DEBUG - and -D_GLIBCXX_DEBUG_PEDANTIC . - (N.B. In GCC 3.4.x and 4.0.0, due to a bug, - -D_GLIBXX_DEBUG_PEDANTIC was also needed. The problem has - been fixed in GCC 4.0.1 and later versions.)

- -

The following library components provide extra debugging - capabilities in debug mode:

-
    -
  • std::basic_string (no safe iterators and see note below)
    • -
  • std::bitset
    • -
  • std::deque
    • -
  • std::list
    • -
  • std::map
    • -
  • std::multimap
    • -
  • std::multiset
    • -
  • std::set
    • -
  • std::vector
    • -
  • std::unordered_map
    • -
  • std::unordered_multimap
    • -
  • std::unordered_set
    • -
  • std::unordered_multiset
    • -
- -

N.B. although there are precondition checks for some string operations, -e.g. operator[], -they will not always be run when using the char and -wchar_t specialisations (std::string and -std::wstring). This is because libstdc++ uses GCC's -extern template extension to provide explicit instantiations -of std::string and std::wstring, and those -explicit instantiations don't include the debug-mode checks. If the -containing functions are inlined then the checks will run, so compiling -with -O1 might be enough to enable them. Alternatively --D_GLIBCXX_EXTERN_TEMPLATE=0 will suppress the declarations -of the explicit instantiations and cause the functions to be instantiated -with the debug-mode checks included, but this is unsupported and not -guaranteed to work. For full debug-mode support you can use the -__gnu_debug::basic_string debugging container directly, -which always works correctly. -

- -

Tips for memory leak hunting

- -

There are various third party memory tracing and debug utilities - that can be used to provide detailed memory allocation information - about C++ code. An exhaustive list of tools is not going to be - attempted, but includes mtrace, valgrind, - mudflap, and the non-free commercial product - purify. In addition, libcwd has a - replacement for the global new and delete operators that can track - memory allocation and deallocation and provide useful memory - statistics. -

- -

Regardless of the memory debugging tool being used, there is one - thing of great importance to keep in mind when debugging C++ code - that uses new and delete: - there are different kinds of allocation schemes that can be used by - std::allocator . For implementation details, see the - mt allocator documentation and - look specifically for GLIBCXX_FORCE_NEW. -

- -

In a nutshell, the default allocator used by - std::allocator is a high-performance pool allocator, and can - give the mistaken impression that in a suspect executable, memory - is being leaked, when in reality the memory "leak" is a pool being - used by the library's allocator and is reclaimed after program - termination. -

- -

For valgrind, there are some specific items to keep in mind. First - of all, use a version of valgrind that will work with current GNU - C++ tools: the first that can do this is valgrind 1.0.4, but later - versions should work at least as well. Second of all, use a - completely unoptimized build to avoid confusing valgrind. Third, - use GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from - cluttering debug information. -

- -

Fourth, it may be necessary to force deallocation in other - libraries as well, namely the "C" library. On linux, this can be - accomplished with the appropriate use of the - __cxa_atexit or atexit functions. -

- -
-   #include <cstdlib>
-
-   extern "C" void __libc_freeres(void);
-
-   void do_something() { }
-
-   int main()
-   {
-     atexit(__libc_freeres);
-     do_something();
-     return 0;
-   }
-
- - -

or, using __cxa_atexit:

- -
-   extern "C" void __libc_freeres(void);
-   extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
-
-   void do_something() { }
-
-   int main()
-   {
-      extern void* __dso_handle __attribute__ ((__weak__));
-      __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 
-                   &__dso_handle ? __dso_handle : NULL);
-      do_test();
-      return 0;
-   }
-
- -

Suggested valgrind flags, given the suggestions above about setting - up the runtime environment, library, and test file, might be: -

-
 
-   valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
-
- - -

Some gdb strategies

-

Many options are available for gdb itself: please see - "GDB features for C++" in the gdb documentation. Also - recommended: the other parts of this manual. -

- -

These settings can either be switched on in at the gdb command - line, or put into a .gdbint file to establish default debugging - characteristics, like so: -

- -
-   set print pretty on
-   set print object on
-   set print static-members on
-   set print vtbl on
-   set print demangle on
-   set demangle-style gnu-v3
-
- - -

Tracking uncaught exceptions

-

The verbose termination handler - gives information about uncaught exceptions which are killing the - program. It is described in the linked-to page. -

- - -

Return to the top of the page or - to the libstdc++ homepage. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/documentation.html b/libstdc++-v3/doc/html/documentation.html deleted file mode 100644 index c5413decd27f..000000000000 --- a/libstdc++-v3/doc/html/documentation.html +++ /dev/null @@ -1,361 +0,0 @@ - - - - - - - The GNU C++ Library - - - - - - -

The GNU C++ Library

- - -

Table of Contents

- -

-The GNU Standard C++ Library is an ongoing project to implement the ISO -14882 Standard C++ library as described in chapters 17 through 27 and -annex D, extensions as described by TR1, and future C++ library -standards still in progress. For those who want to see exactly how far -the project has come, or just want the latest bleeding-edge code, the -up-to-date source is always publicly available over anonymous SVN, -and can be browsed over the web. -

- -

Stable versions of libstdc++ are included with releases of - the GCC compilers. -

- - - - -
-
-

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 - are generated from the sources files themselves. The resultant - documentation is referred to as Source-Level Documentation, and is - useful for examining the signatures of public member functions for - the library classes, finding out what is in a particular include - file, looking at inheritance diagrams, etc. -

-

The source-level documentation for the most recent releases can - be viewed online: -

- -

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/>. - You will almost certainly need to use one of the - mirror sites to download - the tarball. After unpacking, simply load libstdc++-html-*/index.html - into a browser. -

-

Documentation for older releases is available for download only, not - online viewing. -

-

In addition, an initial set of man pages are also available in the - same place as the HTML collections. Start with C++Intro(3). -

- -
-
-

Frequently Asked Questions

- -
-
-

All of these documents (in fact, this entire homepage set) - are bundled with the library source, under the docs - subdirectory, for releases and snapshots. The sole exception is the - automatically-generated source documentation, available separately. -

- - -

Return to the libstdc++ homepage.

- - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - diff --git a/libstdc++-v3/doc/html/ext/ballocator_doc.html b/libstdc++-v3/doc/html/ext/ballocator_doc.html deleted file mode 100644 index 064f5935e726..000000000000 --- a/libstdc++-v3/doc/html/ext/ballocator_doc.html +++ /dev/null @@ -1,426 +0,0 @@ - - - - - Bitmap Allocator - - - - -

Bitmap Allocator

-
-The latest version of this document is always available -at -http://gcc.gnu.org/onlinedocs/libstdc++/ext/ballocator_doc.html.
-
- To the libstdc++ -homepage.
-
-

-As this name suggests, this allocator uses a bit-map to keep track of -the used and unused memory locations for it's book-keeping purposes.
-
-This allocator will make use of 1 single bit to keep track of whether -it has been allocated or not. A bit 1 indicates free, while 0 indicates -allocated. This has been done so that you can easily check a collection -of bits for a free block. This kind of Bitmapped strategy works best -for single object allocations, and with the STL type parameterized -allocators, we do not need to choose any size for the block which will -be represented by a single bit. This will be the size of the parameter -around which the allocator has been parameterized. Thus, close to -optimal performance will result. Hence, this should be used for node -based containers which call the allocate function with an argument of 1.
-
-The bitmapped allocator's internal pool is exponentially growing. -Meaning that internally, the blocks acquired from the Free List Store -will double every time the bitmapped allocator runs out of memory.
-
-

-The macro __GTHREADS decides whether to use Mutex Protection around -every allocation/deallocation. The state of the macro is picked up -automatically from the gthr abstraction layer.
-
-
-

What is the Free List Store?

-
-The Free List Store (referred to as FLS for the remaining part of this -document) is the Global memory pool that is shared by all instances of -the bitmapped allocator instantiated for any type. This maintains a -sorted order of all free memory blocks given back to it by the -bitmapped allocator, and is also responsible for giving memory to the -bitmapped allocator when it asks for more.
-
-Internally, there is a Free List threshold which indicates the Maximum -number of free lists that the FLS can hold internally (cache). -Currently, this value is set at 64. So, if there are more than 64 free -lists coming in, then some of them will be given back to the OS using -operator delete so that at any given time the Free List's size does not -exceed 64 entries. This is done because a Binary Search is used to -locate an entry in a free list when a request for memory comes along. -Thus, the run-time complexity of the search would go up given an -increasing size, for 64 entries however, lg(64) == 6 comparisons are -enough to locate the correct free list if it exists.
-
-Suppose the free list size has reached it's threshold, then the largest -block from among those in the list and the new block will be selected -and given back to the OS. This is done because it reduces external -fragmentation, and allows the OS to use the larger blocks later in an -orderly fashion, possibly merging them later. Also, on some systems, -large blocks are obtained via calls to mmap, so giving them back to -free system resources becomes most important.
-
-The function _S_should_i_give decides the policy that determines -whether the current block of memory should be given to the allocator -for the request that it has made. That's because we may not always have -exact fits for the memory size that the allocator requests. We do this -mainly to prevent external fragmentation at the cost of a little -internal fragmentation. Now, the value of this internal fragmentation -has to be decided by this function. I can see 3 possibilities right -now. Please add more as and when you find better strategies.
-
-
    -
  1. Equal size check. Return true only when the 2 blocks are of equal -size.
    2. -
  2. Difference Threshold: Return true only when the _block_size is -greater than or equal to the _required_size, and if the _BS is > _RS -by a difference of less than some THRESHOLD value, then return true, -else return false.
    3. -
  3. Percentage Threshold. Return true only when the _block_size is -greater than or equal to the _required_size, and if the _BS is > _RS -by a percentage of less than some THRESHOLD value, then return true, -else return false.
    4. -
-
-Currently, (3) is being used with a value of 36% Maximum wastage per -Super Block.
-
-
1) -What is a super block? Why is it needed?
-
-A super block is the block of memory acquired from the FLS from which -the bitmap allocator carves out memory for single objects and satisfies -the user's requests. These super blocks come in sizes that are powers -of 2 and multiples of 32 (_Bits_Per_Block). Yes both at the same time! -That's because the next super block acquired will be 2 times the -previous one, and also all super blocks have to be multiples of the -_Bits_Per_Block value.
-
-2) How does it interact with the free -list store?
-
-The super block is contained in the FLS, and the FLS is responsible for -getting / returning Super Bocks to and from the OS using operator new -as defined by the C++ standard.
-
-
-

How does the allocate function Work?

-
-The allocate function is specialized for single object allocation ONLY. -Thus, ONLY if n == 1, will the bitmap_allocator's specialized algorithm -be used. Otherwise, the request is satisfied directly by calling -operator new.
-
-Suppose n == 1, then the allocator does the following:
-
-
    -
  1. Checks to see whether a free block exists somewhere in a -region of memory close to the last satisfied request. If so, then that -block is marked as allocated in the bit map and given to the user. If -not, then (2) is executed.
    2. -
  2. Is there a free block anywhere after the current block right up to -the end of the memory that we have? If so, that block is found, and the -same procedure is applied as above, and returned to the user. If not, -then (3) is executed.
    3. -
  3. Is there any block in whatever region of memory that we own free? -This is done by checking
    -
    -
      -
    • The use count for each super block, and if that fails then
      • -
    • The individual bit-maps for each super block.
      • -
    -
    -Note: Here we are never touching any of the memory that the user will -be given, and we are confining all memory accesses to a small region of -memory! This helps reduce cache misses. If this succeeds then we apply -the same procedure on that bit-map as (1), and return that block of -memory to the user. However, if this process fails, then we resort to -(4).
    4. -
  4. This process involves Refilling the internal exponentially -growing memory pool. The said effect is achieved by calling -_S_refill_pool which does the following:
    -
    -
      -
    • Gets more memory from the Global Free List of the Required -size.
      • -
    • Adjusts the size for the next call to itself.
      • -
    • Writes the appropriate headers in the bit-maps.
      • -
    • Sets the use count for that super-block just allocated to 0 -(zero).
      • -
    • All of the above accounts to maintaining the basic invariant -for the allocator. If the invariant is maintained, we are sure that all -is well. Now, the same process is applied on the newly acquired free -blocks, which are dispatched accordingly.
      • -
    -
    -
    5. -
-
-Thus, you can clearly see that the allocate function is nothing but a -combination of the next-fit and first-fit algorithm optimized ONLY for -single object allocations.
-
-
-
-

How does the deallocate function work?

-
-The deallocate function again is specialized for single objects ONLY. -For all n belonging to > 1, the operator delete is called without -further ado, and the deallocate function returns.
-
-However for n == 1, a series of steps are performed:
-
-
    -
  1. We first need to locate that super-block which holds the memory -location given to us by the user. For that purpose, we maintain a -static variable _S_last_dealloc_index, which holds the index into the -vector of block pairs which indicates the index of the last super-block -from which memory was freed. We use this strategy in the hope that the -user will deallocate memory in a region close to what he/she -deallocated the last time around. If the check for belongs_to succeeds, -then we determine the bit-map for the given pointer, and locate the -index into that bit-map, and mark that bit as free by setting it.
    2. -
  2. If the _S_last_dealloc_index does not point to the memory block -that we're looking for, then we do a linear search on the block stored -in the vector of Block Pairs. This vector in code is called -_S_mem_blocks. When the corresponding super-block is found, we apply -the same procedure as we did for (1) to mark the block as free in the -bit-map.
    3. -
-
-Now, whenever a block is freed, the use count of that particular super -block goes down by 1. When this use count hits 0, we remove that super -block from the list of all valid super blocks stored in the vector. -While doing this, we also make sure that the basic invariant is -maintained by making sure that _S_last_request and -_S_last_dealloc_index point to valid locations within the vector.
-
-

-

Data Layout for a Super Block:

-
-Each Super Block will be of some size that is a multiple of the number -of Bits Per Block. Typically, this value is chosen as Bits_Per_Byte x -sizeof(size_t). On an x86 system, this gives the figure  8 x -4 = 32. Thus, each Super Block will be of size 32 x Some_Value. This -Some_Value is sizeof(value_type). For now, let it be called 'K'. Thus, -finally, Super Block size is 32 x K bytes.
-
-This value of 32 has been chosen because each size_t has 32-bits -and Maximum use of these can be made with such a figure.
-
-Consider a block of size 64 ints. In memory, it would look like this: -(assume a 32-bit system where, size_t is a 32-bit entity).
-
- - - - - - - - - - -
268
- 		0
- 		4294967295
- 		4294967295
- 		Data -> -Space for 64 ints
-
-
-
-The first Column(268) represents the size of the Block in bytes as seen -by -the Bitmap Allocator. Internally, a global free list is used to keep -track of the free blocks used and given back by the bitmap allocator. -It is this Free List Store that is responsible for writing and managing -this information. Actually the number of bytes allocated in this case -would be: 4 + 4 + (4x2) + (64x4) = 272 bytes, but the first 4 bytes are -an -addition by the Free List Store, so the Bitmap Allocator sees only 268 -bytes. These first 4 bytes about which the bitmapped allocator is not -aware hold the value 268.
-
-What do the remaining values represent?
-
-The 2nd 4 in the expression is the sizeof(size_t) because the -Bitmapped Allocator maintains a used count for each Super Block, which -is initially set to 0 (as indicated in the diagram). This is -incremented every time a block is removed from this super block -(allocated), and decremented whenever it is given back. So, when the -used count falls to 0, the whole super block will be given back to the -Free List Store.
-
-The value 4294967295 represents the integer corresponding to the bit -representation of all bits set: 11111111111111111111111111111111.
-
-The 3rd 4x2 is size of the bitmap itself, which is the size of 32-bits -x 2, -which is 8-bytes, or 2 x sizeof(size_t).
-
-

-Another issue would be whether to keep the all bitmaps in a separate -area in memory, or to keep them near the actual blocks that will be -given out or allocated for the client. After some testing, I've decided -to keep these bitmaps close to the actual blocks. This will help in 2 -ways.
-
-
    -
  1. Constant time access for the bitmap themselves, since no kind of -look up will be needed to find the correct bitmap list or it's -equivalent.
    2. -
  2. And also this would preserve the cache as far as possible.
    3. -
-
-So in effect, this kind of an allocator might prove beneficial from a -purely cache point of view. But this allocator has been made to try and -roll out the defects of the node_allocator, wherein the nodes get -skewed about in memory, if they are not returned in the exact reverse -order or in the same order in which they were allocated. Also, the -new_allocator's book keeping overhead is too much for small objects and -single object allocations, though it preserves the locality of blocks -very well when they are returned back to the allocator.
-
-

-Expected overhead per block would be 1 bit in memory. Also, once the -address of the free list has been found, the cost for -allocation/deallocation would be negligible, and is supposed to be -constant time. For these very reasons, it is very important to minimize -the linear time costs, which include finding a free list with a free -block while allocating, and finding the corresponding free list for a -block while deallocating. Therefore, I have decided that the growth of -the internal pool for this allocator will be exponential as compared to -linear for node_allocator. There, linear time works well, because we -are mainly concerned with speed of allocation/deallocation and memory -consumption, whereas here, the allocation/deallocation part does have -some linear/logarithmic complexity components in it. Thus, to try and -minimize them would be a good thing to do at the cost of a little bit -of memory.
-
-Another thing to be noted is the pool size will double every time -the internal pool gets exhausted, and all the free blocks have been -given away. The initial size of the pool would be sizeof(size_t) x 8 -which is the number of bits in an integer, which can fit exactly -in a CPU register. Hence, the term given is exponential growth of the -internal pool.
-
-
After reading all this, you may -still have a few questions about the internal working of this -allocator, like my friend had!
-
-Well here are the exact questions that he posed:
-
-Q1) The "Data Layout" section is -cryptic. I have no idea of what you are trying to say. Layout of what? -The free-list? Each bitmap? The Super Block?
-
-
The layout of a Super Block of a given -size. In the example, a super block of size 32 x 1 is taken. The -general formula for calculating the size of a super block is -32 x sizeof(value_type) x 2^n, where n ranges from 0 to 32 for 32-bit -systems.
-
-
-Q2) And since I just mentioned the -term `each bitmap', what in the world is meant by it? What does each -bitmap manage? How does it relate to the super block? Is the Super -Block a bitmap as well?
-
-
Good question! Each bitmap is part of -a -Super Block which is made up of 3 parts as I have mentioned earlier. -Re-iterating, 1. The use count, 2. The bit-map for that Super Block. 3. -The actual memory that will be eventually given to the user. Each -bitmap is a multiple of 32 in size. If there are 32 x (2^3) blocks of -single objects to be given, there will be '32 x (2^3)' bits present. -Each -32 bits managing the allocated / free status for 32 blocks. Since each -size_t contains 32-bits, one size_t can manage up to 32 -blocks' status. Each bit-map is made up of a number of size_t, -whose exact number for a super-block of a given size I have just -mentioned.
-
-
-Q3) How do the allocate and deallocate -functions work in regard to bitmaps?
-
-
The allocate and deallocate functions -manipulate the bitmaps and have nothing to do with the memory that is -given to the user. As I have earlier mentioned, a 1 in the bitmap's bit -field indicates free, while a 0 indicates allocated. This lets us check -32 bits at a time to check whether there is at lease one free block in -those 32 blocks by testing for equality with (0). Now, the allocate -function will given a memory block find the corresponding bit in the -bitmap, and will reset it (i.e., make it re-set (0)). And when the -deallocate function is called, it will again set that bit after -locating it to indicate that that particular block corresponding to -this bit in the bit-map is not being used by anyone, and may be used to -satisfy future requests.
-
-e.g.: Consider a bit-map of 64-bits as represented below:
-1111111111111111111111111111111111111111111111111111111111111111
-
-Now, when the first request for allocation of a single object comes -along, the first block in address order is returned. And since the -bit-maps in the reverse order to that of the address order, the last -bit (LSB if the bit-map is considered as a binary word of 64-bits) is -re-set to 0.
-
-The bit-map now looks like this:
-1111111111111111111111111111111111111111111111111111111111111110
-
-
-
-

-(Tech-Stuff, Please stay out if you are not interested in the selection -of certain constants. This has nothing to do with the algorithm per-se, -only with some vales that must be chosen correctly to ensure that the -allocator performs well in a real word scenario, and maintains a good -balance between the memory consumption and the allocation/deallocation -speed).
-
-The formula for calculating the maximum wastage as a percentage:
-
-(32 x k + 1) / (2 x (32 x k + 1 + 32 x c)) x 100.
-
-Where,
-k => The constant overhead per node. eg. for list, it is 8 bytes, -and for map it is 12 bytes.
-c => The size of the base type on which the map/list is -instantiated. Thus, suppose the type1 is int and type2 is double, -they are related by the relation sizeof(double) == 2*sizeof(int). Thus, -all types must have this double size relation for this formula to work -properly.
-
-Plugging-in: For List: k = 8 and c = 4 (int and double), we get:
-33.376%
-
-For map/multimap: k = 12, and c = 4 (int and double), we get:
-37.524%
-
-Thus, knowing these values, and based on the sizeof(value_type), we may -create a function that returns the Max_Wastage_Percentage for us to use.
-
-
See license.html -for copying conditions. Comments and suggestions are welcome, and may -be -sent to the libstdc++ mailing -list.
-
-
- - diff --git a/libstdc++-v3/doc/html/ext/concurrence.html b/libstdc++-v3/doc/html/ext/concurrence.html deleted file mode 100644 index e6bf4438f639..000000000000 --- a/libstdc++-v3/doc/html/ext/concurrence.html +++ /dev/null @@ -1,342 +0,0 @@ - - - - - - - - - - Concurrency Support - - - - - - -

Concurrency Support

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html. -

- -

- To the libstdc++ homepage. -

- - - - -
- - -

The interface for concurrency support is divided into two files: -<ext/atomicity.h> which provides support for atomic operations, -and <ext/concurrence.h>, which provides mutex and lock objects -as well as compile-time data structures for querying thread -support.

- -

It is expected that support for concurrence will evolve into what -is specified in the draft C++0x standard.

- -

- Atomics Interface -

- -

-Two functions and one type form the base of atomic support. -

- - -

The type _Atomic_word is a signed integral type -supporting atomic operations. -

- -

-The two functions functions are: -

- -
-_Atomic_word
-__exchange_and_add_dispatch(volatile _Atomic_word*, int);
-
-void
-__atomic_add_dispatch(volatile _Atomic_word*, int);
-
- -

Both of these functions are declared in the header file -<ext/atomicity.h>, and are in namespace __gnu_cxx. -

- -
    -
  • - -__exchange_and_add_dispatch - -

    Adds the second argument's value to the first argument. Returns the old value. -

    -
    • -
  • - -__atomic_add_dispatch - -

    Adds the second argument's value to the first argument. Has no return value. -

    -
    • -
- -

-These functions forward to one of several specialized helper -functions, depending on the circumstances. For instance, -

- -

- -__exchange_and_add_dispatch - -

- -

-Calls through to either of: -

- -
    -
  • __exchange_and_add -

    Multi-thread version. Inlined if compiler-generated builtin atomics -can be used, otherwise resolved at link time to a non-builtin code -sequence. -

    -
    • - -
  • __exchange_and_add_single -

    Single threaded version. Inlined.

    -
    • -
- -

However, only __exchange_and_add_dispatch -and __atomic_add_dispatch should be used. These functions -can be used in a portable manner, regardless of the specific -environment. They are carefully designed to provide optimum efficiency -and speed, abstracting out atomic accesses when they are not required -(even on hosts that support compiler intrinsics for atomic -operations.) -

- -

-In addition, there are two macros -

- -

- -_GLIBCXX_READ_MEM_BARRIER - -

-

- -_GLIBCXX_WRITE_MEM_BARRIER - -

- -

-Which expand to the appropriate write and read barrier required by the -host hardware and operating system. -

- -

- Pthread Interface -

- -

A thin layer above IEEE 1003.1 (ie pthreads) is used to abstract -the thread interface for GCC. This layer is called "gthread," and is -comprised of one header file that wraps the host's default thread layer with -a POSIX-like interface. -

- -

The file <gthr-default.h> points to the deduced wrapper for -the current host. In libstdc++ implementation files, -<bits/gthr.h> is used to select the proper gthreads file. -

- -

Within libstdc++ sources, all calls to underlying thread functionality -use this layer. More detail as to the specific interface can be found in the source documentation. -

- -

By design, the gthread layer is interoperable with the types, -functions, and usage found in the usual <pthread.h> file, -including pthread_t, pthread_once_t, pthread_create, -etc. -

- -

- Concurrence Interface -

- -

The file <ext/concurrence.h> contains all the higher-level -constructs for playing with threads. In contrast to the atomics layer, -the concurrence layer consists largely of types. All types are defined within namespace __gnu_cxx. -

- -

-These types can be used in a portable manner, regardless of the -specific environment. They are carefully designed to provide optimum -efficiency and speed, abstracting out underlying thread calls and -accesses when compiling for single-threaded situations (even on hosts -that support multiple threads.) -

- -

The enumerated type _Lock_policy details the set of -available locking -policies: _S_single, _S_mutex, -and _S_atomic. -

- -
    -
  • _S_single -

    Indicates single-threaded code that does not need locking. -

    - -
    • -
  • _S_mutex -

    Indicates multi-threaded code using thread-layer abstractions. -

    -
    • -
  • _S_atomic -

    Indicates multi-threaded code using atomic operations. -

    -
    • -
- -

The compile-time constant __default_lock_policy is set -to one of the three values above, depending on characteristics of the -host environment and the current compilation flags. -

- -

Two more datatypes make up the rest of the -interface: __mutex, and __scoped_lock. -

- -

-

- -

The scoped lock idiom is well-discussed within the C++ -community. This version takes a __mutex reference, and -locks it during construction of __scoped_locke and -unlocks it during destruction. This is an efficient way of locking -critical sections, while retaining exception-safety. -

- -

Typical usage of the last two constructs is demonstrated as follows: -

- -
-#include <ext/concurrence.h>
-
-namespace
-{
-  __gnu_cxx::__mutex safe_base_mutex;
-} // anonymous namespace
-
-namespace other
-{
-  void
-  foo()
-  {
-    __gnu_cxx::__scoped_lock sentry(safe_base_mutex);
-    for (int i = 0; i < max;  ++i)
-      {
-	_Safe_iterator_base* __old = __iter;
-	__iter = __iter-<_M_next;
-	__old-<_M_detach_single();
-      }
-}
-
- -

In this sample code, an anonymous namespace is used to keep -the __mutex private to the compilation unit, -and __scoped_lock is used to guard access to the critical -section within the for loop, locking the mutex on creation and freeing -the mutex as control moves out of this block. -

- -

Several exception classes are used to keep track of -concurrence-related errors. These classes -are: __concurrence_lock_error, __concurrence_unlock_error, __concurrence_wait_error, -and __concurrence_broadcast_error. -

- - - -

- Details on builtin atomic support and library fallbacks -

- -

The functions for atomic operations described above are either -implemented via compiler intrinsics (if the underlying host is -capable) or by library fallbacks.

- -

Compiler intrinsics (builtins) are always preferred. However, as -the compiler builtins for atomics are not universally implemented, -using them directly is problematic, and can result in undefined -function calls. (An example of an undefined symbol from the use -of __sync_fetch_and_add on an unsupported host is a -missing reference to __sync_fetch_and_add_4.) -

- -

In addition, on some hosts the compiler intrinsics are enabled -conditionally, via the -march command line flag. This makes -usage vary depending on the target hardware and the flags used during -compile. -

- -

If builtins are possible, _GLIBCXX_ATOMIC_BUILTINS -will be defined. -

- - -

For the following hosts, intrinsics are enabled by default. -

- -
    -
  • alpha
    • -
  • ia64
    • -
  • powerpc
    • -
  • s390
    • -
- -

For others, some form of -march may work. On -non-ancient x86 hardware, -march=native usually does the -trick.

- -

For hosts without compiler intrinsics, but with capable -hardware, hand-crafted assembly is selected. This is the case for the following hosts: -

- -
    -
  • cris
    • -
  • hppa
    • -
  • i386
    • -
  • i486
    • -
  • m48k
    • -
  • mips
    • -
  • sparc
    • -
- -

And for the rest, a simulated atomic lock via pthreads. -

- -

Detailed information about compiler intrinsics for atomic operations can be found in the GCC documentation. -

- -

More details on the library fallbacks from the porting section. -

- - - - - - diff --git a/libstdc++-v3/doc/html/ext/debug_mode.html b/libstdc++-v3/doc/html/ext/debug_mode.html deleted file mode 100644 index 7e9d9bafae92..000000000000 --- a/libstdc++-v3/doc/html/ext/debug_mode.html +++ /dev/null @@ -1,578 +0,0 @@ - - - - - - - - - - Design of the libstdc++ debug mode - - - - -

Design of the libstdc++ debug mode

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/debug_mode.html. -

- -

- To the libstdc++ homepage. -

- - - - -
-

Debug mode design

-

The libstdc++ debug mode replaces unsafe (but efficient) standard - containers and iterators with semantically equivalent safe standard - containers and iterators to aid in debugging user programs. The - following goals directed the design of the libstdc++ debug mode:

- -
    - -
  • Correctness: the libstdc++ debug mode must not change - the semantics of the standard library for all cases specified in - the ANSI/ISO C++ standard. The essence of this constraint is that - any valid C++ program should behave in the same manner regardless - of whether it is compiled with debug mode or release mode. In - particular, entities that are defined in namespace std in release - mode should remain defined in namespace std in debug mode, so that - legal specializations of namespace std entities will remain - valid. A program that is not valid C++ (e.g., invokes undefined - behavior) is not required to behave similarly, although the debug - mode will abort with a diagnostic when it detects undefined - behavior.
    • - -
  • Performance: the additional of the libstdc++ debug mode - must not affect the performance of the library when it is compiled - in release mode. Performance of the libstdc++ debug mode is - secondary (and, in fact, will be worse than the release - mode).
    • - -
  • Usability: the libstdc++ debug mode should be easy to - use. It should be easily incorporated into the user's development - environment (e.g., by requiring only a single new compiler switch) - and should produce reasonable diagnostics when it detects a - problem with the user program. Usability also involves detection - of errors when using the debug mode incorrectly, e.g., by linking - a release-compiled object against a debug-compiled object if in - fact the resulting program will not run correctly.
    • - -
  • Minimize recompilation: While it is expected that - users recompile at least part of their program to use debug - mode, the amount of recompilation affects the - detect-compile-debug turnaround time. This indirectly affects the - usefulness of the debug mode, because debugging some applications - may require rebuilding a large amount of code, which may not be - feasible when the suspect code may be very localized. There are - several levels of conformance to this requirement, each with its - own usability and implementation characteristics. In general, the - higher-numbered conformance levels are more usable (i.e., require - less recompilation) but are more complicated to implement than - the lower-numbered conformance levels. -
      -
    1. Full recompilation: The user must recompile his or - her entire application and all C++ libraries it depends on, - including the C++ standard library that ships with the - compiler. This must be done even if only a small part of the - program can use debugging features.
      2. - -
    2. Full user recompilation: The user must recompile - his or her entire application and all C++ libraries it depends - on, but not the C++ standard library itself. This must be done - even if only a small part of the program can use debugging - features. This can be achieved given a full recompilation - system by compiling two versions of the standard library when - the compiler is installed and linking against the appropriate - one, e.g., a multilibs approach.
      3. - -
    3. Partial recompilation: The user must recompile the - parts of his or her application and the C++ libraries it - depends on that will use the debugging facilities - directly. This means that any code that uses the debuggable - standard containers would need to be recompiled, but code - that does not use them (but may, for instance, use IOStreams) - would not have to be recompiled.
      4. - -
    4. Per-use recompilation: The user must recompile the - parts of his or her application and the C++ libraries it - depends on where debugging should occur, and any other code - that interacts with those containers. This means that a set of - translation units that accesses a particular standard - container instance may either be compiled in release mode (no - checking) or debug mode (full checking), but must all be - compiled in the same way; a translation unit that does not see - that standard container instance need not be recompiled. This - also means that a translation unit A that contains a - particular instantiation - (say, std::vector<int>) compiled in release - mode can be linked against a translation unit B that - contains the same instantiation compiled in debug mode (a - feature not present with partial recompilation). While this - behavior is technically a violation of the One Definition - Rule, this ability tends to be very important in - practice. The libstdc++ debug mode supports this level of - recompilation.
      5. - -
    5. Per-unit recompilation: The user must only - recompile the translation units where checking should occur, - regardless of where debuggable standard containers are - used. This has also been dubbed "-g mode", - because the -g compiler switch works in this way, - emitting debugging information at a per--translation-unit - granularity. We believe that this level of recompilation is in - fact not possible if we intend to supply safe iterators, leave - the program semantics unchanged, and not regress in - performance under release mode because we cannot associate - extra information with an iterator (to form a safe iterator) - without either reserving that space in release mode - (performance regression) or allocating extra memory associated - with each iterator with new (changes the program - semantics).
      6. -
    -
    • -
- -

Other implementations

-

There are several existing implementations of debug modes for C++ - standard library implementations, although none of them directly - supports debugging for programs using libstdc++. The existing - implementations include:

-
    -
  • SafeSTL: - SafeSTL was the original debugging version of the Standard Template - Library (STL), implemented by Cay S. Horstmann on top of the - Hewlett-Packard STL. Though it inspired much work in this area, it - has not been kept up-to-date for use with modern compilers or C++ - standard library implementations.
    • - -
  • STLport: STLport is a free - implementation of the C++ standard library derived from the SGI implementation, and - ported to many other platforms. It includes a debug mode that uses a - wrapper model (that in some way inspired the libstdc++ debug mode - design), although at the time of this writing the debug mode is - somewhat incomplete and meets only the "Full user recompilation" (2) - recompilation guarantee by requiring the user to link against a - different library in debug mode vs. release mode.
    • - -
  • Metrowerks - CodeWarrior: The C++ standard library that ships with Metrowerks - CodeWarrior includes a debug mode. It is a full debug-mode - implementation (including debugging for CodeWarrior extensions) and - is easy to use, although it meets only the "Full recompilation" (1) - recompilation guarantee.
    • -
- -

Debug mode design methodology

-

This section provides an overall view of the design of the - libstdc++ debug mode and details the relationship between design - decisions and the stated design goals.

- -

The wrapper model

-

The libstdc++ debug mode uses a wrapper model where the debugging - versions of library components (e.g., iterators and containers) form - a layer on top of the release versions of the library - components. The debugging components first verify that the operation - is correct (aborting with a diagnostic if an error is found) and - will then forward to the underlying release-mode container that will - perform the actual work. This design decision ensures that we cannot - regress release-mode performance (because the release-mode - containers are left untouched) and partially enables mixing debug and release code at link time, - although that will not be discussed at this time.

- -

Two types of wrappers are used in the implementation of the debug - mode: container wrappers and iterator wrappers. The two types of - wrappers interact to maintain relationships between iterators and - their associated containers, which are necessary to detect certain - types of standard library usage errors such as dereferencing - past-the-end iterators or inserting into a container using an - iterator from a different container.

- -

Safe iterators

-

Iterator wrappers provide a debugging layer over any iterator that - is attached to a particular container, and will manage the - information detailing the iterator's state (singular, - dereferenceable, etc.) and tracking the container to which the - iterator is attached. Because iterators have a well-defined, common - interface the iterator wrapper is implemented with the iterator - adaptor class template __gnu_debug::_Safe_iterator, - which takes two template parameters:

- -
    -
  • Iterator: The underlying iterator type, which must - be either the iterator or const_iterator - typedef from the sequence type this iterator can reference.
    • - -
  • Sequence: The type of sequence that this iterator - references. This sequence must be a safe sequence (discussed below) - whose iterator or const_iterator typedef - is the type of the safe iterator.
    • -
- -

Safe sequences (containers)

-

Container wrappers provide a debugging layer over a particular - container type. Because containers vary greatly in the member - functions they support and the semantics of those member functions - (especially in the area of iterator invalidation), container - wrappers are tailored to the container they reference, e.g., the - debugging version of std::list duplicates the entire - interface of std::list, adding additional semantic - checks and then forwarding operations to the - real std::list (a public base class of the debugging - version) as appropriate. However, all safe containers inherit from - the class template __gnu_debug::_Safe_sequence, - instantiated with the type of the safe container itself (an instance - of the curiously recurring template pattern).

- -

The iterators of a container wrapper will be - safe iterators that reference sequences - of this type and wrap the iterators provided by the release-mode - base class. The debugging container will use only the safe - iterators within its own interface (therefore requiring the user to - use safe iterators, although this does not change correct user - code) and will communicate with the release-mode base class with - only the underlying, unsafe, release-mode iterators that the base - class exports.

- -

The debugging version of std::list will have the - following basic structure:

- -
-template<typename _Tp, typename _Allocator = allocator<_Tp>
-  class debug-list :
-    public release-list<_Tp, _Allocator>,
-    public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> >
-  {
-    typedef release-list<_Tp, _Allocator> _Base;
-    typedef debug-list<_Tp, _Allocator>   _Self;
-
-  public:
-    typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self>       iterator;
-    typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> const_iterator;
-
-    // duplicate std::list interface with debugging semantics
-  };
-
- -

Precondition checking

-

The debug mode operates primarily by checking the preconditions of - all standard library operations that it supports. Preconditions that - are always checked (regardless of whether or not we are in debug - mode) are checked via the __check_xxx macros defined - and documented in the source - file include/debug/debug.h. Preconditions that may or - may not be checked, depending on the debug-mode - macro _GLIBCXX_DEBUG, are checked via - the __requires_xxx macros defined and documented in the - same source file. Preconditions are validated using any additional - information available at run-time, e.g., the containers that are - associated with a particular iterator, the position of the iterator - within those containers, the distance between two iterators that may - form a valid range, etc. In the absence of suitable information, - e.g., an input iterator that is not a safe iterator, these - precondition checks will silently succeed.

- -

The majority of precondition checks use the aforementioned macros, - which have the secondary benefit of having prewritten debug - messages that use information about the current status of the - objects involved (e.g., whether an iterator is singular or what - sequence it is attached to) along with some static information - (e.g., the names of the function parameters corresponding to the - objects involved). When not using these macros, the debug mode uses - either the debug-mode assertion - macro _GLIBCXX_DEBUG_ASSERT , its pedantic - cousin _GLIBCXX_DEBUG_PEDASSERT, or the assertion - check macro that supports more advance formulation of error - messages, _GLIBCXX_DEBUG_VERIFY. These macros are - documented more thoroughly in the debug mode source code.

- -

Release- and debug-mode coexistence

-

The libstdc++ debug mode is the first debug mode we know of that - is able to provide the "Per-use recompilation" (4) guarantee, that - allows release-compiled and debug-compiled code to be linked and - executed together without causing unpredictable behavior. This - guarantee minimizes the recompilation that users are required to - perform, shortening the detect-compile-debug bughunting cycle - and making the debug mode easier to incorporate into development - environments by minimizing dependencies.

- -

Achieving link- and run-time coexistence is not a trivial - implementation task. To achieve this goal we required a small - extension to the GNU C++ compiler (described in the GCC Manual for - C++ Extensions, see strong - using), and a complex organization of debug- and - release-modes. The end result is that we have achieved per-use - recompilation but have had to give up some checking of the - std::basic_string class template (namely, safe - iterators). -

- -

Compile-time coexistence of release- and - debug-mode components

-

Both the release-mode components and the debug-mode - components need to exist within a single translation unit so that - the debug versions can wrap the release versions. However, only one - of these components should be user-visible at any particular - time with the standard name, e.g., std::list.

- -

In release mode, we define only the release-mode version of the - component with its standard name and do not include the debugging - component at all. The release mode version is defined within the - namespace std. Minus the namespace associations, this - method leaves the behavior of release mode completely unchanged from - its behavior prior to the introduction of the libstdc++ debug - mode. Here's an example of what this ends up looking like, in - C++.

- -
-namespace std
-{
-  template<typename _Tp, typename _Alloc = allocator<_Tp> >
-    class list
-    {
-      // ...
-     };
-} // namespace std
-
- -

In debug mode we include the release-mode container (which is now -defined in in the namespace __norm) and also the -debug-mode container. The debug-mode container is defined within the -namespace __debug, which is associated with namespace -std via the GNU namespace association extension. This -method allows the debug and release versions of the same component to -coexist at compile-time and link-time without causing an unreasonable -maintenance burden, while minimizing confusion. Again, this boils down -to C++ code as follows:

- -
-namespace std
-{
-  namespace __norm
-  {
-    template<typename _Tp, typename _Alloc = allocator<_Tp> >
-      class list
-      {
-        // ...
-      };
-  } // namespace __gnu_norm
-
-  namespace __debug
-  {
-    template<typename _Tp, typename _Alloc = allocator<_Tp> >
-      class list
-      : public __norm::list<_Tp, _Alloc>,
-        public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> >
-      {
-        // ...
-      };
-  } // namespace __norm
-
-  using namespace __debug __attribute__ ((strong));
-}
-
- -

Link- and run-time coexistence of release- and - debug-mode components

- -

Because each component has a distinct and separate release and -debug implementation, there are are no issues with link-time -coexistence: the separate namespaces result in different mangled -names, and thus unique linkage.

- -

However, components that are defined and used within the C++ -standard library itself face additional constraints. For instance, -some of the member functions of std::moneypunct return -std::basic_string. Normally, this is not a problem, but -with a mixed mode standard library that could be using either -debug-mode or release-mode basic_string objects, things -get more complicated. As the return value of a function is not -encoded into the mangled name, there is no way to specify a -release-mode or a debug-mode string. In practice, this results in -runtime errors. A simplified example of this problem is as follows. -

- -

Take this translation unit, compiled in debug-mode:

-
-// -D_GLIBCXX_DEBUG
-#include <string>
-
-std::string test02();
- 
-std::string test01()
-{
-  return test02();
-}
- 
-int main()
-{
-  test01();
-  return 0;
-}
-
- -

... and linked to this translation unit, compiled in release mode:

- -
-#include <string>
- 
-std::string
-test02()
-{
-  return std::string("toast");
-}
-
- -

For this reason we cannot easily provide safe iterators for - the std::basic_string class template, as it is present - throughout the C++ standard library. For instance, locale facets - define typedefs that include basic_string: in a mixed - debug/release program, should that typedef be based on the - debug-mode basic_string or the - release-mode basic_string? While the answer could be - "both", and the difference hidden via renaming a la the - debug/release containers, we must note two things about locale - facets:

- -
    -
  1. They exist as shared state: one can create a facet in one - translation unit and access the facet via the same type name in a - different translation unit. This means that we cannot have two - different versions of locale facets, because the types would not be - the same across debug/release-mode translation unit barriers.
    2. - -
  2. They have virtual functions returning strings: these functions - mangle in the same way regardless of the mangling of their return - types (see above), and their precise signatures can be relied upon - by users because they may be overridden in derived classes.
    3. -
- -

With the design of libstdc++ debug mode, we cannot effectively hide - the differences between debug and release-mode strings from the - user. Failure to hide the differences may result in unpredictable - behavior, and for this reason we have opted to only - perform basic_string changes that do not require ABI - changes. The effect on users is expected to be minimal, as there are - simple alternatives (e.g., __gnu_debug::basic_string), - and the usability benefit we gain from the ability to mix debug- and - release-compiled translation units is enormous.

- -

Alternatives for Coexistence

-

The coexistence scheme above was chosen over many alternatives, - including language-only solutions and solutions that also required - extensions to the C++ front end. The following is a partial list of - solutions, with justifications for our rejection of each.

- -
    -
  • Completely separate debug/release libraries: This is by - far the simplest implementation option, where we do not allow any - coexistence of debug- and release-compiled translation units in a - program. This solution has an extreme negative affect on usability, - because it is quite likely that some libraries an application - depends on cannot be recompiled easily. This would not meet - our usability or minimize recompilation criteria - well.
    • - -
  • Add a Debug boolean template parameter: - Partial specialization could be used to select the debug - implementation when Debug == true, and the state - of _GLIBCXX_DEBUG could decide whether the - default Debug argument is true - or false. This option would break conformance with the - C++ standard in both debug and release modes. This would - not meet our correctness criteria.
    • - -
  • Packaging a debug flag in the allocators: We could - reuse the Allocator template parameter of containers - by adding a sentinel wrapper debug<> that - signals the user's intention to use debugging, and pick up - the debug<> allocator wrapper in a partial - specialization. However, this has two drawbacks: first, there is a - conformance issue because the default allocator would not be the - standard-specified std::allocator<T>. Secondly - (and more importantly), users that specify allocators instead of - implicitly using the default allocator would not get debugging - containers. Thus this solution fails the correctness - criteria.
    • - -
  • Define debug containers in another namespace, and employ - a using declaration (or directive): This is an - enticing option, because it would eliminate the need for - the link_name extension by aliasing the - templates. However, there is no true template aliasing mechanism - is C++, because both using directives and using - declarations disallow specialization. This method fails - the correctness criteria.
    • - -
  • Use implementation-specific properties of anonymous - namespaces. - See this post - - This method fails the correctness criteria.
    • - -
  • Extension: allow reopening on namespaces: This would - allow the debug mode to effectively alias the - namespace std to an internal namespace, such - as __gnu_std_debug, so that it is completely - separate from the release-mode std namespace. While - this will solve some renaming problems and ensure that - debug- and release-compiled code cannot be mixed unsafely, it ensures that - debug- and release-compiled code cannot be mixed at all. For - instance, the program would have two std::cout - objects! This solution would fails the minimize - recompilation requirement, because we would only be able to - support option (1) or (2).
    • - -
  • Extension: use link name: This option involves - complicated re-naming between debug-mode and release-mode - components at compile time, and then a g++ extension called - link name to recover the original names at link time. There - are two drawbacks to this approach. One, it's very verbose, - relying on macro renaming at compile time and several levels of - include ordering. Two, ODR issues remained with container member - functions taking no arguments in mixed-mode settings resulting in - equivalent link names, vector::push_back() being - one example. - See link - name
    • -
- -

Other options may exist for implementing the debug mode, many of - which have probably been considered and others that may still be - lurking. This list may be expanded over time to include other - options that we could have implemented, but in all cases the full - ramifications of the approach (as measured against the design goals - for a libstdc++ debug mode) should be considered first. The DejaGNU - testsuite includes some testcases that check for known problems with - some solutions (e.g., the using declaration solution - that breaks user specialization), and additional testcases will be - added as we are able to identify other typical problem cases. These - test cases will serve as a benchmark by which we can compare debug - mode implementations.

- - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/ext/howto.html b/libstdc++-v3/doc/html/ext/howto.html deleted file mode 100644 index 2e88c660a617..000000000000 --- a/libstdc++-v3/doc/html/ext/howto.html +++ /dev/null @@ -1,675 +0,0 @@ - - - - - - - - - - - libstdc++ HOWTO: Extensions - - - - - - - - - -

Extensions

- -

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

-

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

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

Contents

- - -
- - - -

Ropes and trees and hashes, oh my!

-

The SGI headers

- 
-     <hash_map>
-     <hash_set>
-     <rope>
-     <slist>
-     <rb_tree>
-
-

are all here; - <hash_map> and <hash_set> - are deprecated but available as backwards-compatible extensions, - as discussed further below. <rope> is the - SGI specialization for large strings ("rope," - "large strings," get it? Love that geeky humor.) - <slist> is a singly-linked list, for when the - doubly-linked list<> is too much space - overhead, and <rb_tree> exposes the red-black - tree classes used in the implementation of the standard maps and - sets. -

-

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

-

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

-

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

Okay, about the SGI hashing classes... these classes have been - deprecated by the unordered_set, unordered_multiset, unordered_map, - unordered_multimap containers in TR1 and the upcoming C++0x, and - may be removed in future releases. -

- -

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 - the standard. Of those, some are intended purely for the implementors, - 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.
    • -
  • Extensions allowing filebufs to be constructed from - stdio types are described in the - chapter 27 notes.
    • -
  • The C++ Standard Library Technical Report adds many new features - to the library, see FAQ 5.5.
    • -
-

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

- -
-

Compile-time checks

-

Currently libstdc++ uses the concept checkers from the Boost - library to perform optional - compile-time checking of template instantiations of the standard - containers. They are described in the linked-to page. -

-

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

- -
-

LWG Issues

-

Everybody's got issues. Even the C++ Standard Library. -

-

The Library Working Group, or LWG, is the ISO subcommittee responsible - for making changes to the library. They periodically publish an - Issues List containing problems and possible solutions. As they reach - a consensus on proposed solutions, we often incorporate the solution - into libstdc++. -

-

Here are the issues which have resulted in code changes to the library. - The links are to the specific defect reports from a partial - copy of the Issues List. You can read the full version online - at the ISO C++ - Committee homepage, linked to on the - GCC "Readings" - page. If - you spend a lot of time reading the issues, we recommend downloading - the ZIP file and reading them locally. -

-

(NB: partial copy means that not all links within - the lwg-*.html pages will work. - Specifically, links to defect reports that have not been accorded full - DR status will probably break. Rather than trying to mirror the - entire issues list on our overworked web server, we recommend you go - to the LWG homepage instead.) -

-

- If a DR is not listed here, we may simply not have gotten to it yet; - feel free to submit a patch. Search the include/bits and src - directories for appearances of _GLIBCXX_RESOLVE_LIB_DEFECTS for - 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... -
- -
19: - "Noconv" definition too vague -
-
If codecvt::do_in returns noconv there are - no changes to the values in [to, to_limit). -
- -
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. -
- -
60: - What is a formatted input function? -
-
This DR made many widespread changes to basic_istream - and basic_ostream all of which have been implemented. -
- -
63: - Exception-handling policy for unformatted output -
-
Make the policy consistent with that of formatted input, unformatted - input, and formatted output. -
- -
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. -
- -
75: - Contradiction in codecvt::length's argument types -
-
Change the first parameter to stateT& and implement - the new effects paragraph. -
- -
83: - string::npos vs. string::max_size() -
-
Safety checks on the size of the string should test against - max_size() rather than npos. -
- -
90: - Incorrect description of operator>> for strings -
-
The effect contain isspace(c,getloc()) which must be - replaced by isspace(c,is.getloc()). -
- -
91: - Description of operator>> and getline() for string<> - might cause endless loop -
-
They behave as a formatted input function and as an unformatted - input function, respectively (except that getline is - not required to set gcount). -
- -
103: - set::iterator is required to be modifiable, but this allows - modification of keys. -
-
For associative containers where the value type is the same as - the key type, both iterator and const_iterator - are constant iterators. -
- -
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. -
- - - -
167: - Improper use of traits_type::length() -
-
op<< with a const char* was - calculating an incorrect number of characters to write. -
- -
169: - Bad efficiency of overflow() mandated -
-
Grow efficiently the internal array object. -
- -
171: - Strange seekpos() semantics due to joint position -
-
Quite complex to summarize... -
- -
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. -
- -
231: - Precision in iostream? -
-
For conversion from a floating-point type, str.precision() - is specified in the conversion specification. -
- -
233: - Insertion hints in associative containers -
-
Implement N1780, first check before then check after, insert as close - to hint as possible. -
- -
235: - No specification of default ctor for reverse_iterator -
-
The declaration of reverse_iterator lists a default constructor. - However, no specification is given what this constructor should do. -
- -
241: - Does unique_copy() require CopyConstructible and Assignable? -
-
Add a helper for forward_iterator/output_iterator, fix the existing - one for input_iterator/output_iterator to not rely on Assignability. -
- -
243: - get and getline when sentry reports failure -
-
Store a null character only if the character array has a non-zero size. -
- -
251: - basic_stringbuf missing allocator_type -
-
This nested typedef was originally not specified. -
- -
253: - valarray helper functions are almost entirely useless -
-
Make the copy constructor and copy-assignment operator declarations - public in gslice_array, indirect_array, mask_array, slice_array; provide - definitions. -
- -
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. -
- -
271: - basic_iostream missing typedefs -
-
The typedefs it inherits from its base classes can't be used, since - (for example) basic_iostream<T>::traits_type is ambiguous. -
- -
275: - Wrong type in num_get::get() overloads -
-
Similar to 118. -
- -
280: - Comparison of reverse_iterator to const reverse_iterator -
-
Add global functions with two template parameters. - (NB: not added for now a templated assignment operator) -
- -
292: - Effects of a.copyfmt (a) -
-
If (this == &rhs) do nothing. -
- -
300: - List::merge() specification incomplete -
-
If (this == &x) do nothing. -
- -
303: - Bitset input operator underspecified -
-
Basically, compare the input character to is.widen(0) - and is.widen(1). -
- -
305: - Default behavior of codecvt<wchar_t, char, mbstate_t>::length() -
-
Do not specify what codecvt<wchar_t, char, mbstate_t>::do_length - must return. -
- -
328: - Bad sprintf format modifier in money_put<>::do_put() -
-
Change the format string to "%.0Lf". -
- -
365: - Lack of const-qualification in clause 27 -
-
Add const overloads of is_open. -
- -
389: - Const overload of valarray::operator[] returns by value -
-
Change it to return a const T&. -
- -
402: - Wrong new expression in [some_]allocator::construct -
-
Replace "new" with "::new". -
- -
409: - Closing an fstream should clear the error state -
-
Have open clear the error flags. -
- -
431: - Swapping containers with unequal allocators -
-
Implement Option 3, as per N1599. -
- -
432: - stringbuf::overflow() makes only one write position - available -
-
Implement the resolution, beyond DR 169. -
- -
434: - bitset::to_string() hard to use -
-
Add three overloads, taking fewer template arguments. -
- -
438: - Ambiguity in the "do the right thing" clause -
-
Implement the resolution, basically cast less. -
- -
453: - basic_stringbuf::seekoff need not always fail for an empty stream -
-
Don't fail if the next pointer is null and newoff is zero. -
- -
455: - cerr::tie() and wcerr::tie() are overspecified -
-
Initialize cerr tied to cout and wcerr tied to wcout. -
- -
464: - Suggestion for new member functions in standard containers -
-
Add data() to std::vector and - at(const key_type&) to std::map. -
- -
508: - Bad parameters for ranlux64_base_01 -
-
Fix the parameters. -
- -
512: - Seeding subtract_with_carry_01 from a single unsigned long -
-
Construct a linear_congruential engine and seed with it. -
- -
526: - Is it undefined if a function in the standard changes in - parameters? -
-
Use &value. -
- -
538: - 241 again: Does unique_copy() require CopyConstructible - and Assignable? -
-
In case of input_iterator/output_iterator rely on Assignability of - input_iterator' value_type. -
- -
541: - shared_ptr template assignment and void -
-
Add an auto_ptr<void> specialization. -
- -
543: - valarray slice default constructor -
-
Follow the straightforward proposed resolution. -
- -
586: - string inserter not a formatted function -
-
Change it to be a formatted output function (i.e. catch exceptions). -
- -
596: - 27.8.1.3 Table 112 omits "a+" and "a+b" modes -
-
Add the missing modes to fopen_mode. -
- -
660: - Missing bitwise operations -
-
Add the missing operations. -
- -
693: - std::bitset::all() missing -
-
Add it, consistently with the discussion. -
- -
695: - ctype<char>::classic_table() not accessible -
-
Make the member functions table and classic_table public. -
- -
-

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

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/ext/mt_allocator.html b/libstdc++-v3/doc/html/ext/mt_allocator.html deleted file mode 100644 index b53e7e6200ec..000000000000 --- a/libstdc++-v3/doc/html/ext/mt_allocator.html +++ /dev/null @@ -1,560 +0,0 @@ - - - - - - - - - - A fixed-size, multi-thread optimized allocator - - - - - - - -

A fixed-size, multi-thread optimized allocator

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/ext/mt_allocator.html. -

- -

- To the libstdc++ homepage. -

- - -
-

- Introduction -

- -

The mt allocator [hereinafter referred to simply as "the -allocator"] is a fixed size (power of two) allocator that was -initially developed specifically to suit the needs of multi threaded -applications [hereinafter referred to as an MT application]. Over time -the allocator has evolved and been improved in many ways, in -particular it now also does a good job in single threaded applications -[hereinafter referred to as a ST application]. (Note: In this -document, when referring to single threaded applications this also -includes applications that are compiled with gcc without thread -support enabled. This is accomplished using ifdef's on -__GTHREADS). This allocator is tunable, very flexible, and capable of -high-performance. -

- -

-The aim of this document is to describe - from an application point of -view - the "inner workings" of the allocator. -

- -

- Design Overview -

- -

There are three general components to the allocator: a datum -describing the characteristics of the memory pool, a policy class -containing this pool that links instantiation types to common or -individual pools, and a class inheriting from the policy class that is -the actual allocator. -

- -

The datum describing pools characteristics is -

-
-  template<bool _Thread>
-    class __pool
-
-

This class is parametrized on thread support, and is explicitly -specialized for both multiple threads (with bool==true) -and single threads (via bool==false.) It is possible to -use a custom pool datum instead of the default class that is provided. -

- -

There are two distinct policy classes, each of which can be used -with either type of underlying pool datum. -

- -
-  template<bool _Thread>
-    struct __common_pool_policy
-
-  template<typename _Tp, bool _Thread>
-    struct __per_type_pool_policy
-
- -

The first policy, __common_pool_policy, implements a -common pool. This means that allocators that are instantiated with -different types, say char and long will both -use the same pool. This is the default policy. -

- -

The second policy, __per_type_pool_policy, implements -a separate pool for each instantiating type. Thus, char -and long will use separate pools. This allows per-type -tuning, for instance. -

- -

Putting this all together, the actual allocator class is -

-
-  template<typename _Tp, typename _Poolp = __default_policy>
-    class __mt_alloc : public __mt_alloc_base<_Tp>,  _Poolp
-
-

This class has the interface required for standard library allocator -classes, namely member functions allocate and -deallocate, plus others. -

- -

- Tunable parameters -

- -

Certain allocation parameters can be modified, or tuned. There -exists a nested struct __pool_base::_Tune that contains all -these parameters, which include settings for -

-
    -
  • Alignment
    • -
  • Maximum bytes before calling ::operator new directly
    • -
  • Minimum bytes
    • -
  • Size of underlying global allocations
    • -
  • Maximum number of supported threads
    • -
  • Migration of deallocations to the global free list
    • -
  • Shunt for global new and delete
    • -
-

Adjusting parameters for a given instance of an allocator can only -happen before any allocations take place, when the allocator itself is -initialized. For instance: -

-
-#include <ext/mt_allocator.h>
-
-struct pod
-{
-  int i;
-  int j;
-};
-
-int main()
-{
-  typedef pod value_type;
-  typedef __gnu_cxx::__mt_alloc<value_type> allocator_type;
-  typedef __gnu_cxx::__pool_base::_Tune tune_type;
-
-  tune_type t_default;
-  tune_type t_opt(16, 5120, 32, 5120, 20, 10, false);
-  tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
-
-  tune_type t;
-  t = allocator_type::_M_get_options();  
-  allocator_type::_M_set_options(t_opt);
-  t = allocator_type::_M_get_options();  
-
-  allocator_type a;
-  allocator_type::pointer p1 = a.allocate(128);
-  allocator_type::pointer p2 = a.allocate(5128);
-
-  a.deallocate(p1, 128);
-  a.deallocate(p2, 5128);
-
-  return 0;
-}
-
- -

- Initialization -

- -

-The static variables (pointers to freelists, tuning parameters etc) -are initialized as above, or are set to the global defaults. -

- -

-The very first allocate() call will always call the -_S_initialize_once() function. In order to make sure that this -function is called exactly once we make use of a __gthread_once call -in MT applications and check a static bool (_S_init) in ST -applications. -

- -

-The _S_initialize() function: -- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool - _S_force_new to true and then returns. This will cause subsequent calls to - allocate() to return memory directly from a new() call, and deallocate will - only do a delete() call. -

- -

-- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT - applications will: - - Calculate the number of bins needed. A bin is a specific power of two size - of bytes. I.e., by default the allocator will deal with requests of up to - 128 bytes (or whatever the value of _S_max_bytes is when _S_init() is - called). This means that there will be bins of the following sizes - (in bytes): 1, 2, 4, 8, 16, 32, 64, 128. - - - Create the _S_binmap array. All requests are rounded up to the next - "large enough" bin. I.e., a request for 29 bytes will cause a block from - the "32 byte bin" to be returned to the application. The purpose of - _S_binmap is to speed up the process of finding out which bin to use. - I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes). -

-

- - Create the _S_bin array. This array consists of bin_records. There will be - as many bin_records in this array as the number of bins that we calculated - earlier. I.e., if _S_max_bytes = 128 there will be 8 entries. - Each bin_record is then initialized: - - bin_record->first = An array of pointers to block_records. There will be - as many block_records pointers as there are maximum number of threads - (in a ST application there is only 1 thread, in a MT application there - are _S_max_threads). - This holds the pointer to the first free block for each thread in this - bin. I.e., if we would like to know where the first free block of size 32 - for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ] - - The above created block_record pointers members are now initialized to - their initial values. I.e. _S_bin[ n ].first[ n ] = NULL; -

- -

-- Additionally a MT application will: - - Create a list of free thread id's. The pointer to the first entry - is stored in _S_thread_freelist_first. The reason for this approach is - that the __gthread_self() call will not return a value that corresponds to - the maximum number of threads allowed but rather a process id number or - something else. So what we do is that we create a list of thread_records. - This list is _S_max_threads long and each entry holds a size_t thread_id - which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads. - Each time a thread calls allocate() or deallocate() we call - _S_get_thread_id() which looks at the value of _S_thread_key which is a - thread local storage pointer. If this is NULL we know that this is a newly - created thread and we pop the first entry from this list and saves the - pointer to this record in the _S_thread_key variable. The next time - we will get the pointer to the thread_record back and we use the - thread_record->thread_id as identification. I.e., the first thread that - calls allocate will get the first record in this list and thus be thread - number 1 and will then find the pointer to its first free 32 byte block - in _S_bin[ 5 ].first[ 1 ] - When we create the _S_thread_key we also define a destructor - (_S_thread_key_destr) which means that when the thread dies, this - thread_record is returned to the front of this list and the thread id - can then be reused if a new thread is created. - This list is protected by a mutex (_S_thread_freelist_mutex) which is only - locked when records are removed/added to the list. -

-

- - Initialize the free and used counters of each bin_record: - - bin_record->free = An array of size_t. This keeps track of the number - of blocks on a specific thread's freelist in each bin. I.e., if a thread - has 12 32-byte blocks on it's freelists and allocates one of these, this - counter would be decreased to 11. - - - bin_record->used = An array of size_t. This keeps track of the number - of blocks currently in use of this size by this thread. I.e., if a thread - has made 678 requests (and no deallocations...) of 32-byte blocks this - counter will read 678. - - The above created arrays are now initialized with their initial values. - I.e. _S_bin[ n ].free[ n ] = 0; -

-

- - Initialize the mutex of each bin_record: The bin_record->mutex - is used to protect the global freelist. This concept of a global - freelist is explained in more detail in the section "A multi - threaded example", but basically this mutex is locked whenever a - block of memory is retrieved or returned to the global freelist - for this specific bin. This only occurs when a number of blocks - are grabbed from the global list to a thread specific list or when - a thread decides to return some blocks to the global freelist. -

- -

Notes about deallocation. This allocator does not explicitly -release memory. Because of this, memory debugging programs like -valgrind or purify may notice leaks: sorry about this -inconvenience. Operating systems will reclaim allocated memory at -program termination anyway. If sidestepping this kind of noise is -desired, there are three options: use an allocator, like -new_allocator that releases memory while debugging, use -GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a -custom pool datum that releases resources on destruction.

- -

On systems with the function __cxa_atexit, the -allocator can be forced to free all memory allocated before program -termination with the member function -__pool_type::_M_destroy. However, because this member -function relies on the precise and exactly-conforming ordering of -static destructors, including those of a static local -__pool object, it should not be used, ever, on systems -that don't have the necessary underlying support. In addition, in -practice, forcing deallocation can be tricky, as it requires the -__pool object to be fully-constructed before the object -that uses it is fully constructed. For most (but not all) STL -containers, this works, as an instance of the allocator is constructed -as part of a container's constructor. However, this assumption is -implementation-specific, and subject to change. For an example of a -pool that frees memory, see the following - - example. -

- -

- A single threaded example (and a primer for the multi threaded example!) -

- -

-Let's start by describing how the data on a freelist is laid out in memory. -This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes): -

-
-+----------------+
-| next* ---------|--+  (_S_bin[ 3 ].first[ 3 ] points here)
-|                |  |
-|                |  |
-|                |  |
-+----------------+  |
-| thread_id = 3  |  |
-|                |  |
-|                |  |
-|                |  |
-+----------------+  |
-| DATA           |  |  (A pointer to here is what is returned to the
-|                |  |   the application when needed)
-|                |  |
-|                |  |
-|                |  |
-|                |  |
-|                |  |
-|                |  |
-+----------------+  |
-+----------------+  |
-| next*          |<-+  (If next == NULL it's the last one on the list)
-|                |
-|                |
-|                |
-+----------------+
-| thread_id = 3  |
-|                |
-|                |
-|                |
-+----------------+
-| DATA           |
-|                |
-|                |
-|                |
-|                |
-|                |
-|                |
-|                |
-+----------------+
-
- -

-With this in mind we simplify things a bit for a while and say that there is -only one thread (a ST application). In this case all operations are made to -what is referred to as the global pool - thread id 0 (No thread may be -assigned this id since they span from 1 to _S_max_threads in a MT application). -

-

-When the application requests memory (calling allocate()) we first look at the -requested size and if this is > _S_max_bytes we call new() directly and return. -

-

-If the requested size is within limits we start by finding out from which -bin we should serve this request by looking in _S_binmap. -

-

-A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of -this size on the freelist (0). If this is not NULL - fine, just remove the -block that _S_bin[ bin ].first[ 0 ] points to from the list, -update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data. -

-

-If the freelist is empty (the pointer is NULL) we must get memory from the -system and build us a freelist within this memory. All requests for new memory -is made in chunks of _S_chunk_size. Knowing the size of a block_record and -the bytes that this bin stores we then calculate how many blocks we can create -within this chunk, build the list, remove the first block, update the pointer -(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data. -

- -

-Deallocation is equally simple; the pointer is casted back to a block_record -pointer, lookup which bin to use based on the size, add the block to the front -of the global freelist and update the pointer as needed -(_S_bin[ bin ].first[ 0 ]). -

- -

-The decision to add deallocated blocks to the front of the freelist was made -after a set of performance measurements that showed that this is roughly 10% -faster than maintaining a set of "last pointers" as well. -

- -

- A multi threaded example -

- -

-In the ST example we never used the thread_id variable present in each block. -Let's start by explaining the purpose of this in a MT application. -

- -

-The concept of "ownership" was introduced since many MT applications -allocate and deallocate memory to shared containers from different -threads (such as a cache shared amongst all threads). This introduces -a problem if the allocator only returns memory to the current threads -freelist (I.e., there might be one thread doing all the allocation and -thus obtaining ever more memory from the system and another thread -that is getting a longer and longer freelist - this will in the end -consume all available memory). -

- -

-Each time a block is moved from the global list (where ownership is -irrelevant), to a threads freelist (or when a new freelist is built -from a chunk directly onto a threads freelist or when a deallocation -occurs on a block which was not allocated by the same thread id as the -one doing the deallocation) the thread id is set to the current one. -

- -

-What's the use? Well, when a deallocation occurs we can now look at -the thread id and find out if it was allocated by another thread id -and decrease the used counter of that thread instead, thus keeping the -free and used counters correct. And keeping the free and used counters -corrects is very important since the relationship between these two -variables decides if memory should be returned to the global pool or -not when a deallocation occurs. -

- -

-When the application requests memory (calling allocate()) we first -look at the requested size and if this is > _S_max_bytes we call new() -directly and return. -

- -

-If the requested size is within limits we start by finding out from which -bin we should serve this request by looking in _S_binmap. -

- -

-A call to _S_get_thread_id() returns the thread id for the calling thread -(and if no value has been set in _S_thread_key, a new id is assigned and -returned). -

- -

-A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are -any blocks of this size on the current threads freelist. If this is -not NULL - fine, just remove the block that _S_bin[ bin ].first[ -thread_id ] points to from the list, update _S_bin[ bin ].first[ -thread_id ], update the free and used counters and return a pointer to -that blocks data. -

- -

-If the freelist is empty (the pointer is NULL) we start by looking at -the global freelist (0). If there are blocks available on the global -freelist we lock this bins mutex and move up to block_count (the -number of blocks of this bins size that will fit into a _S_chunk_size) -or until end of list - whatever comes first - to the current threads -freelist and at the same time change the thread_id ownership and -update the counters and pointers. When the bins mutex has been -unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ] -points to from the list, update _S_bin[ bin ].first[ thread_id ], -update the free and used counters, and return a pointer to that blocks -data. -

- -

-The reason that the number of blocks moved to the current threads -freelist is limited to block_count is to minimize the chance that a -subsequent deallocate() call will return the excess blocks to the -global freelist (based on the _S_freelist_headroom calculation, see -below). -

- -

-However if there isn't any memory on the global pool we need to get -memory from the system - this is done in exactly the same way as in a -single threaded application with one major difference; the list built -in the newly allocated memory (of _S_chunk_size size) is added to the -current threads freelist instead of to the global. -

- -

-The basic process of a deallocation call is simple: always add the -block to the front of the current threads freelist and update the -counters and pointers (as described earlier with the specific check of -ownership that causes the used counter of the thread that originally -allocated the block to be decreased instead of the current threads -counter). -

- -

-And here comes the free and used counters to service. Each time a -deallocation() call is made, the length of the current threads -freelist is compared to the amount memory in use by this thread. -

- -

-Let's go back to the example of an application that has one thread -that does all the allocations and one that deallocates. Both these -threads use say 516 32-byte blocks that was allocated during thread -creation for example. Their used counters will both say 516 at this -point. The allocation thread now grabs 1000 32-byte blocks and puts -them in a shared container. The used counter for this thread is now -1516. -

- -

-The deallocation thread now deallocates 500 of these blocks. For each -deallocation made the used counter of the allocating thread is -decreased and the freelist of the deallocation thread gets longer and -longer. But the calculation made in deallocate() will limit the length -of the freelist in the deallocation thread to _S_freelist_headroom % -of it's used counter. In this case, when the freelist (given that the -_S_freelist_headroom is at it's default value of 10%) exceeds 52 -(516/10) blocks will be returned to the global pool where the -allocating thread may pick them up and reuse them. -

- -

-In order to reduce lock contention (since this requires this bins -mutex to be locked) this operation is also made in chunks of blocks -(just like when chunks of blocks are moved from the global freelist to -a threads freelist mentioned above). The "formula" used can probably -be improved to further reduce the risk of blocks being "bounced back -and forth" between freelists. -

- -
-

Return to the top of the page or - to the libstdc++ homepage. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/ext/parallel_mode.html b/libstdc++-v3/doc/html/ext/parallel_mode.html deleted file mode 100644 index 7ca8dbe937cc..000000000000 --- a/libstdc++-v3/doc/html/ext/parallel_mode.html +++ /dev/null @@ -1,593 +0,0 @@ - - - - - - - - - - The libstdc++ parallel mode - - - - - -

The libstdc++ parallel mode

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/parallel_mode.html. -

- -

- To the libstdc++ homepage. -

- - -
-

The libstdc++ parallel mode is an experimental parallel -implementation of many algorithms the C++ Standard Library. -

- -

-Several of the standard algorithms, for instance -std::sort, are made parallel using OpenMP -annotations. These parallel mode constructs and can be invoked by -explicit source declaration or by compiling existing sources with a -specific compiler flag. -

- -

The libstdc++ parallel mode

- -

The libstdc++ parallel mode performs parallelization of algorithms, -function objects, classes, and functions in the C++ Standard.

- -

Using the libstdc++ parallel mode

- -

To use the libstdc++ parallel mode, compile your application with - the compiler flag -D_GLIBCXX_PARALLEL -fopenmp. This - will link in libgomp, the GNU OpenMP implementation, - whose presence is mandatory. In addition, hardware capable of atomic - operations is mandatory. Actually activating these atomic - operations may require explicit compiler flags on some targets - (like sparc and x86), such as -march=i686, - -march=native or -mcpu=v9. -

- -

Note that the _GLIBCXX_PARALLEL define may change the - sizes and behavior of standard class templates such as - std::search, and therefore one can only link code - compiled with parallel mode and code compiled without parallel mode - if no instantiation of a container is passed between the two - translation units. Parallel mode functionality has distinct linkage, - and cannot be confused with normal mode symbols.

- - -

The following library components in the include -<numeric> are included in the parallel mode:

-
    -
  • std::accumulate
    • -
  • std::adjacent_difference
    • -
  • std::inner_product
    • -
  • std::partial_sum
    • -
- -

The following library components in the include -<algorithm> are included in the parallel mode:

-
    -
  • std::adjacent_find
    • -
  • std::count
    • -
  • std::count_if
    • -
  • std::equal
    • -
  • std::find
    • -
  • std::find_if
    • -
  • std::find_first_of
    • -
  • std::for_each
    • -
  • std::generate
    • -
  • std::generate_n
    • -
  • std::lexicographical_compare
    • -
  • std::mismatch
    • -
  • std::search
    • -
  • std::search_n
    • -
  • std::transform
    • -
  • std::replace
    • -
  • std::replace_if
    • -
  • std::max_element
    • -
  • std::merge
    • -
  • std::min_element
    • -
  • std::nth_element
    • -
  • std::partial_sort
    • -
  • std::partition
    • -
  • std::random_shuffle
    • -
  • std::set_union
    • -
  • std::set_intersection
    • -
  • std::set_symmetric_difference
    • -
  • std::set_difference
    • -
  • std::sort
    • -
  • std::stable_sort
    • -
  • std::unique_copy
    • -
- -

The following library components in the includes -<set> and <map> are included in the parallel mode:

-
    -
  • std::(multi_)map/set<T>::(multi_)map/set(Iterator begin, Iterator end) (bulk construction)
    • -
  • std::(multi_)map/set<T>::insert(Iterator begin, Iterator end) (bulk insertion)
    • -
- - -

Using the parallel algorithms without parallel mode

- -

When it is not feasible to recompile your entire application, or - only specific algorithms need to be parallel-aware, individual - parallel algorithms can be made available explicitly. These - parallel algorithms are functionally equivalent to the standard - drop-in algorithms used in parallel mode, but they are available in - a separate namespace as GNU extensions and may be used in programs - compiled with either release mode or with parallel mode. The - following table provides the names and headers of the parallel - algorithms: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AlgorithmHeaderParallel algorithmParallel header
std::accumulate<numeric>__gnu_parallel::accumulate<parallel/numeric>
std::adjacent_difference<numeric>__gnu_parallel::adjacent_difference<parallel/numeric>
std::inner_product<numeric>__gnu_parallel::inner_product<parallel/numeric>
std::partial_sum<numeric>__gnu_parallel::partial_sum<parallel/numeric>
std::adjacent_find<algorithm>__gnu_parallel::adjacent_find<parallel/algorithm>
std::count<algorithm>__gnu_parallel::count<parallel/algorithm>
std::count_if<algorithm>__gnu_parallel::count_if<parallel/algorithm>
std::equal<algorithm>__gnu_parallel::equal<parallel/algorithm>
std::find<algorithm>__gnu_parallel::find<parallel/algorithm>
std::find_if<algorithm>__gnu_parallel::find_if<parallel/algorithm>
std::find_first_of<algorithm>__gnu_parallel::find_first_of<parallel/algorithm>
std::for_each<algorithm>__gnu_parallel::for_each<parallel/algorithm>
std::generate<algorithm>__gnu_parallel::generate<parallel/algorithm>
std::generate_n<algorithm>__gnu_parallel::generate_n<parallel/algorithm>
std::lexicographical_compare<algorithm>__gnu_parallel::lexicographical_compare<parallel/algorithm>
std::mismatch<algorithm>__gnu_parallel::mismatch<parallel/algorithm>
std::search<algorithm>__gnu_parallel::search<parallel/algorithm>
std::search_n<algorithm>__gnu_parallel::search_n<parallel/algorithm>
std::transform<algorithm>__gnu_parallel::transform<parallel/algorithm>
std::replace<algorithm>__gnu_parallel::replace<parallel/algorithm>
std::replace_if<algorithm>__gnu_parallel::replace_if<parallel/algorithm>
std::max_element<algorithm>__gnu_parallel::max_element<parallel/algorithm>
std::merge<algorithm>__gnu_parallel::merge<parallel/algorithm>
std::min_element<algorithm>__gnu_parallel::min_element<parallel/algorithm>
std::nth_element<algorithm>__gnu_parallel::nth_element<parallel/algorithm>
std::partial_sort<algorithm>__gnu_parallel::partial_sort<parallel/algorithm>
std::partition<algorithm>__gnu_parallel::partition<parallel/algorithm>
std::random_shuffle<algorithm>__gnu_parallel::random_shuffle<parallel/algorithm>
std::set_union<algorithm>__gnu_parallel::set_union<parallel/algorithm>
std::set_intersection<algorithm>__gnu_parallel::set_intersection<parallel/algorithm>
std::set_symmetric_difference<algorithm>__gnu_parallel::set_symmetric_difference<parallel/algorithm>
std::set_difference<algorithm>__gnu_parallel::set_difference<parallel/algorithm>
std::sort<algorithm>__gnu_parallel::sort<parallel/algorithm>
std::stable_sort<algorithm>__gnu_parallel::stable_sort<parallel/algorithm>
std::unique_copy<algorithm>__gnu_parallel::unique_copy<parallel/algorithm>
- - -

Parallel mode semantics

- -

The parallel mode STL algorithms are currently not exception-safe, -i. e. user-defined functors must not throw exceptions. -

- -

Since the current GCC OpenMP implementation does not support -OpenMP parallel regions in concurrent threads, -it is not possible to call parallel STL algorithm in -concurrent threads, either. -It might work with other compilers, though.

- - -

Configuration and Tuning

- -

Some algorithm variants can be enabled/disabled/selected at compile-time. -See -<compiletime_settings.h> and -See -<features.h> for details. -

- -

-To specify the number of threads to be used for an algorithm, -use omp_set_num_threads. -To force a function to execute sequentially, -even though parallelism is switched on in general, -add __gnu_parallel::sequential_tag() -to the end of the argument list. -

- -

-Parallelism always incurs some overhead. Thus, it is not -helpful to parallelize operations on very small sets of data. -There are measures to avoid parallelizing stuff that is not worth it. -For each algorithm, a minimum problem size can be stated, -usually using the variable -__gnu_parallel::Settings::[algorithm]_minimal_n. -Please see -<settings.h> for details.

- - - -

Interface basics and general design

- -

All parallel algorithms are intended to have signatures that are -equivalent to the ISO C++ algorithms replaced. For instance, the -std::adjacent_find function is declared as: -

-
-namespace std
-{
-  template<typename _FIter>
-    _FIter
-    adjacent_find(_FIter, _FIter);
-}
-
- -

-Which means that there should be something equivalent for the parallel -version. Indeed, this is the case: -

- -
-namespace std
-{
-  namespace __parallel
-  {
-    template<typename _FIter>
-      _FIter
-      adjacent_find(_FIter, _FIter);
-
-    ...
-  }
-}
-
- -

But.... why the elipses? -

- -

The elipses in the example above represent additional overloads -required for the parallel version of the function. These additional -overloads are used to dispatch calls from the ISO C++ function -signature to the appropriate parallel function (or sequential -function, if no parallel functions are deemed worthy), based on either -compile-time or run-time conditions. -

- -

Compile-time conditions are referred to as "embarrassingly -parallel," and are denoted with the appropriate dispatch object, ie -one of __gnu_parallel::sequential_tag, -__gnu_parallel::parallel_tag, -__gnu_parallel::balanced_tag, -__gnu_parallel::unbalanced_tag, -__gnu_parallel::omp_loop_tag, or -__gnu_parallel::omp_loop_static_tag. -

- -

Run-time conditions depend on the hardware being used, the number -of threads available, etc., and are denoted by the use of the enum -__gnu_parallel::parallelism. Values of this enum include -__gnu_parallel::sequential, -__gnu_parallel::parallel_unbalanced, -__gnu_parallel::parallel_balanced, -__gnu_parallel::parallel_omp_loop, -__gnu_parallel::parallel_omp_loop_static, or -__gnu_parallel::parallel_taskqueue. -

- -

Putting all this together, the general view of overloads for the -parallel algorithms look like this: -

-
    -
  • ISO C++ signature
    • -
  • ISO C++ signature + sequential_tag argument
    • -
  • ISO C++ signature + parallelism argument
    • -
- -

Please note that the implementation may use additional functions -(designated with the _switch suffix) to dispatch from the -ISO C++ signature to the correct parallel version. Also, some of the -algorithms do not have support for run-time conditions, so the last -overload is therefore missing. -

- - -

Relevant namespaces

- -

One namespace contain versions of code that are explicitly sequential: -__gnu_serial. -

- -

Two namespaces contain the parallel mode: -std::__parallel and __gnu_parallel. -

- -

Parallel implementations of standard components, including -template helpers to select parallelism, are defined in namespace -std::__parallel. For instance, std::transform from -<algorithm> has a parallel counterpart in -std::__parallel::transform from -<parallel/algorithm>. In addition, these parallel -implementations are injected into namespace -__gnu_parallel with using declarations. -

- -

Support and general infrastructure is in namespace -__gnu_parallel. -

- -

More information, and an organized index of types and functions -related to the parallel mode on a per-namespace basis, can be found in -the generated source documentation. -

- -

Testing

- -

Both the normal conformance and regression tests and the -supplemental performance tests work.

- -

To run the conformance and regression tests with the parallel mode -active,

-make check-parallel - -

The log and summary files for conformance testing are in the -testsuite/parallel directory.

- -

To run the performance tests with the parallel mode active,

-make check-performance-parallel - -

The result file for performance testing are in the -testsuite directory, in the file -libstdc++_performance.sum. In addition, the policy-based -containers have their own visualizations, which have additional -software dependencies than the usual bare-boned text file, and can be -generated by using the make doc-performance rule in the -testsuite's Makefile.

- -

Return to the top of the page or - to the libstdc++ homepage. -

- - -

References / Further Reading

- -

-Johannes Singler, Peter Sanders, Felix Putze. The Multi-Core Standard Template Library. Euro-Par 2007: Parallel Processing. (LNCS 4641) -

- -

-Leonor Frias, Johannes Singler: Parallelization of Bulk Operations for STL Dictionaries. Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS) -

- - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/ext/sgiexts.html b/libstdc++-v3/doc/html/ext/sgiexts.html deleted file mode 100644 index 64b8e3138c19..000000000000 --- a/libstdc++-v3/doc/html/ext/sgiexts.html +++ /dev/null @@ -1,253 +0,0 @@ - - - - - - - - - - HP/SGI STL extensions - - - - - - - - -

HP/SGI STL extensions

- -

This page describes the extensions that SGI made to the STL subset - of the Standard C++ Library, which also includes work from the - originating HP codebase. This work is the basis for much of - libstdc++, and where possible these extensions have been - preserved. -

- -

What follows is a listing of these extensions, according to the - chapters of the library that they extend - (see the chapter-specific - notes for a description). Not every chapter has extensions, - and existing extensions may be removed (or moved) as their - functionality is standardized. -

- -

Descriptions range from the scanty to the verbose. Also check - the generated documentation - for notes and comments, especially for entries marked with '*'. - For more complete doumentation, see the SGI website. - For really complete documentation, consider perusing a - copy of Matt Austern's book "Generic Programming and the STL." -

- -

Back to the libstdc++ extensions. -

- - - -
-

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 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. *
    • -
  • 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.
    • -
-

20.4.1 can use several different allocators; they are described on the - main extensions page. -

-

20.4.3 is extended with a special version of - get_temporary_buffer taking a second argument. The argument - 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 - uninitialized_copy_n. * -

-

Return to the main extensions page or - to the homepage. -

- - -
-

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

-

The old pre-standard bit_vector class is present for - backwards compatibility. It is simply a typedef for the - vector<bool> specialization. -

-

The bitset class has a number of extensions, described in the - rest of this item. First, we'll mention that this implementation of - bitset<N> is specialized for cases where N number of - bits will fit into a single word of storage. If your choice of N is - within that range (<=32 on i686-pc-linux-gnu, for example), then all - of the operations will be faster. -

-

There are - 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 - 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 - 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 - reference (a nested type). However, this implementation does - no range-checking on the index argument, which is in keeping with other - containers' op[] requirements. The defect report's proposed - resolution calls for range-checking to be done. We'll just wait and see... -

-

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

-

Return to the main extensions page or - to the homepage. -

- - -
-

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

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 - modified, and the function returns nothing. -

-

Return to the main extensions page or - to the homepage. -

- - -
-

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

-

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_sorted tests whether or not a range is sorted in - nondescending order.
    • -
-

25.3.8 (lexigraphical_compare) is extended with -

- 
-   lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
-                                 _InputIter2 first2, _InputIter2 last2)
-

which does... what? -

-

Return to the main extensions page or - to the homepage. -

- - -
-

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 - 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. - The operation functor must be associative. -

-

The iota function wins the award for Extension With the - 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. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - diff --git a/libstdc++-v3/doc/html/faq/index.html b/libstdc++-v3/doc/html/faq/index.html deleted file mode 100644 index ff6cd65c9a6e..000000000000 --- a/libstdc++-v3/doc/html/faq/index.html +++ /dev/null @@ -1,1215 +0,0 @@ - - - - - - - - - libstdc++ FAQ - - - - - - -

libstdc++ Frequently Asked Questions

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/faq/. The main documentation - page is at - - http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html. -

- -

- To the libstdc++ homepage. -

- - -
-

Questions

-
    -
  1. General Information - -
      -
    1. What is libstdc++?
      2. -
    2. Why should I use libstdc++?
      3. -
    3. Who's in charge of it?
      4. -
    4. [removed]
      5. -
    5. When is libstdc++ going to be finished?
      6. -
    6. How do I contribute to the effort?
      7. -
    7. What happened to libg++? I need that!
      8. -
    8. What if I have more questions?
      9. -
    9. What are the license terms for libstdc++?
      10. -
    -
    2. - -
  2. Installation -
      -
    1. How do I install libstdc++?
      2. -
    2. [removed]
      3. -
    3. What is this SVN thing that you keep - mentioning?
      4. -
    4. How do I know if it works?
      5. -
    5. This library is HUGE! And what's libsupc++?
      6. -
    6. Why do I get an error saying - libstdc++.so.X is missing when I - run my program?
      7. -
    -
    3. - -
  3. Platform-Specific Issues -
      -
    1. Can libstdc++ be used with <my - favorite compiler>?
      2. -
    2. [removed]
      3. -
    3. [removed]
      4. -
    4. I can't use 'long long' on Solaris
      5. -
    5. _XOPEN_SOURCE / - _GNU_SOURCE / etc is always defined -
      6. -
    6. OS X ctype.h is broken! How can I hack it?
      7. -
    7. Threading is broken on i386
      8. -
    8. Recent GNU/Linux glibc required?
      9. -
    9. Can't use wchar_t/wstring on FreeBSD
      10. -
    10. MIPS atomic operations
      11. -
    -
    4. - -
  4. Known Bugs and Non-Bugs -
      -
    1. What works already?
      2. -
    2. Bugs in gcc/g++ (not libstdc++)
      3. -
    3. Bugs in the C++ language/lib specification
      4. -
    4. Things in libstdc++ that only look like bugs -
      5. -
    5. Aw, that's easy to fix!
      6. -
    -
    5. - -
  5. Miscellaneous -
      -
    1. string::iterator is not char*; - vector<T>::iterator is not T*
      2. -
    2. What's next after libstdc++?
      3. -
    3. What about the STL from SGI?
      4. -
    4. Extensions and Backward Compatibility
      5. -
    5. Does libstdc++ support TR1?
      6. -
    6. Is libstdc++ thread-safe?
      7. -
    7. How do I get a copy of the ISO C++ Standard?
      8. -
    8. What's an ABI and why is it so messy?
      9. -
    9. How do I make std::vector<T>::capacity() - == std::vector<T>::size?
      10. -
    -
    6. - -
- -
- - - -

1.0 General Information

- -

1.1 What is libstdc++?

-

The GNU Standard C++ Library v3 is an - ongoing project to implement the ISO 14882 Standard C++ library - as described in chapters 17 through 27 and annex D. - For those who want to see exactly how - far the project has come, or just want the latest - bleeding-edge code, the up-to-date source is available over - anonymous SVN, and can even be browsed over the - web. -

- -
-

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 - of the C++ Standard Library. However, all existing C++ - implementations are (as the Draft Standard used to say) - "incomplet and incorrekt," and many suffer from - limitations of the compilers that use them. -

-

The GNU C/C++/FORTRAN/<pick-a-language> compiler - (gcc, g++, etc) is widely considered to be - one of the leading compilers in the world. Its development - is overseen by the - GCC team. All of - the rapid development and near-legendary - portability - that are the hallmarks of an open-source project are being - applied to libstdc++. -

-

That means that all of the Standard classes and functions - (such as string, vector<>, iostreams, - and algorithms) will be freely available and fully compliant. - Programmers will no longer need to "roll their own" - 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. - Benjamin Kosnik, Gabriel Dos Reis, Phil Edwards, Ulrich Drepper, - Loren James Rittle, and Paolo Carlini are the lead maintainers of - the SVN archive. -

-

Development and discussion is held on the libstdc++ mailing - list. Subscribing to the list, or searching the list - archives, is open to everyone. You can read instructions for - doing so on the homepage. - If you have questions, ideas, code, or are just curious, sign up! -

- -
-

1.4 How do I get libstdc++?

- -

Stable versions of libstdc++-v3 are included with releases of - the GCC compilers. -

- -
-

1.5 When is libstdc++ going to be finished?

- -

Nathan Myers gave the best of all possible answers, responding to a - 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 - list (see above, or the homepage) is a very good idea if you - have something to contribute, or if you have spare time and - want to help. Contributions don't have to be in the form of - source code; anybody who is willing to help write - documentation, for example, or has found a bug in code that - 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 - projects, and is only being kicked along to support older code. -

-

The libg++ was designed and created when there was no Standard - to provide guidance. Classes like linked lists are now provided - for by list<T> and do not need to be created by - genclass. (For that matter, templates exist now and - are well-supported, whereas genclass (mostly) predates them.) -

-

There are other classes in libg++ that are not specified in the - ISO Standard (e.g., statistical analysis). While there are a - lot of really useful things that are used by a lot of people - (e.g., statistics :-), the Standards Committee couldn't include - everything, and so a lot of those "obvious" classes - didn't get included. -

-

Since libstdc++ is an implementation of the Standard Library, we - have no plans at this time to include non-Standard utilities - in the implementation, however handy they are. (The extensions - provided in the SGI STL aren't maintained by us and don't get - a lot of our attention, because they don't require a lot of our - time.) It is entirely plausible that the "useful stuff" - from libg++ might be extracted into an updated utilities library, - but nobody has started such a project yet. -

-

(The Boost site houses free - C++ libraries that do varying things, and happened to be started - by members of the Standards Committee. Certain "useful - stuff" classes will probably migrate there.) -

-

For the bold and/or desperate, the - GCC extensions page - describes where to find the last libg++ source. -

- -
-

1.8 What if I have more questions?

-

If you have read the README file, and your - question remains unanswered, then just ask the mailing list. - At present, you do not need to be subscribed to the list to - send a message to it. More information is available on the - homepage (including how to browse the list archives); to send - to the list, use - libstdc++@gcc.gnu.org. -

-

If you have a question that you think should be included here, - or if you have a question about a question/answer here, - contact Phil Edwards - or Gabriel Dos Reis. -

- -
-

1.9 What are the license terms for libstdc++?

-

See our license description - for these and related questions. -

- -
-

2.0 Installation

-

2.1 How do I install libstdc++?

-

Complete instructions are not given here (this is a FAQ, not - an installation document), but the tools required are few: -

-
    -
  • A 3.x or later release of GCC. Either install a suitable - package for your system, or compile GCC from the sources. - Note that building GCC - is much easier and more automated than building the GCC - 2.[78] series was. If you are using GCC 2.95, you can - still build earlier snapshots of libstdc++ but you - should consult the documentation that comes with the - sources, the instructions are no longer included here. -
    • -
  • GNU Make is required to build GCC 3.4 and later. -
    • -
  • The GNU Autotools are needed if you are messing with - the configury or makefiles. -
    • -
-

The file documentation.html - links to documentation of the steps necessary to build, install, - and use the library. Instructions for configuring the library - with flags such as --enable-threads are there also. -

-

The top-level install.html file contains - the exact build and installation instructions. You may wish to - browse those files over ViewVC ahead of time to get a feel for - what's required. -

- -
-

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 SVN thing that you - keep mentioning?

-

Subversion 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 - Subversion home page has a better description. -

-

The "anonymous client checkout" feature of SVN is - similar to anonymous FTP in that it allows anyone to retrieve - the latest libstdc++ sources. -

-

After the first of April, American users will have a - "/pharmacy" command-line option... - -

- -
-

2.4 How do I know if it works?

-

libstdc++ comes with its own testsuite. You do not need - to actually install the library ("make - install") to run the testsuite, but you do need - DejaGNU, as described - here. -

-

To run the testsuite on the library after building it, use - "make check" while in your build directory. To run - the testsuite on the library after building and installing it, - use "make check-install" instead. -

-

If you find bugs in the testsuite programs themselves, or if you - think of a new test program that should be added to the suite, - please write up your idea and send it to the list! -

- -
-

2.5 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 - static archive library, only the necessary object files are copied - into your executable, not the entire library. Unfortunately, even - if you only need a single function or variable from an object file, - the entire object file is extracted. (There's nothing unique to C++ - or libstdc++ about this; it's just common behavior, given here - for background reasons.) -

-

Some of the object files which make up libstdc++.a are rather large. - If you create a statically-linked executable with - -static, those large object files are suddenly part - of your executable. Historically the best way around this was to - only place a very few functions (often only a single one) in each - source/object file; then extracting a single function is the same - as extracting a single .o file. For libstdc++ this is only - possible to a certain extent; the object files in question contain - template classes and template functions, pre-instantiated, and - splitting those up causes severe maintenance headaches. -

-

It's not a bug, and it's not really a problem. Nevertheless, some - people don't like it, so here are two pseudo-solutions: -

-

If the only functions from libstdc++.a which you need are - language support functions (those listed in clause 18 of the - standard, e.g., new and delete), - then try linking against libsupc++.a (Using - gcc instead of g++ and explicitly - linking in -lsupc++ for the final link step will - do it). This library contains only those support routines, - one per object file. But if you are using anything from the - rest of the library, such as IOStreams or vectors, then - you'll still need pieces from libstdc++.a. -

-

The second method is one we hope to incorporate into the library - build process. Some platforms can place each function and variable - into its own section in a .o file. The GNU linker can then perform - garbage collection on unused sections; this reduces the situation - to only copying needed functions into the executable, as before, - but all happens automatically. -

-

Unfortunately the garbage collection in GNU ld is buggy; sections - (corresponding to functions and variables) which are used - are mistakenly removed, leading to horrible crashes when your - executable starts up. For the time being, this feature is not used - when building the library. -

- -
-

2.6 Why do I get an error saying - libstdc++.so.X is missing when I run - my program?

-

Depending on your platform and library version, the message might - be similar to one of the following: -

- 
-    ./a.out: error while loading shared libraries: libstdc++.so.6: cannot open shared object file: No such file or directory
-
-    /usr/libexec/ld-elf.so.1: Shared object "libstdc++.so.6" not found
- -

This doesn't mean that the shared library isn't installed, only - that the dynamic linker can't find it. When a dynamically-linked - executable is run the linker finds and loads the required shared - libraries by searching a pre-configured list of directories. If - the directory where you've installed libstdc++ is not in this - list then the libraries won't be found. The simplest way to fix - this is to use the LD_LIBRARY_PATH environment - variable, which is a colon-separated list of directories in which - the linker will search for shared libraries: -

- 
-    LD_LIBRARY_PATH=${prefix}/lib:$LD_LIBRARY_PATH
-    export LD_LIBRARY_PATH
-

The exact environment variable to use will depend on your platform, - e.g. DYLD_LIBRARY_PATH for Darwin, - LD_LIBRARY_PATH_32/LD_LIBRARY_PATH_64 for Solaris 32-/64-bit, - LD_LIBRARYN32_PATH/LD_LIBRARY64_PATH for Irix N32/64-bit ABIs - and SHLIB_PATH for HP-UX. -

-

See the man pages for ld(1), ldd(1) and - ldconfig(8) for more information. The dynamic linker - has different names on different platforms but the man page is - usually called something such as ld.so / rtld / dld.so. -

- -
-

3.0 Platform-Specific Issues

-

3.1 Can libstdc++ be used with <my - favorite compiler>?

-

Probably not. Yet.

-

Because GCC advances so rapidly, development and testing of - libstdc++ is being done almost entirely under that compiler. - If you are curious about whether other, lesser compilers - (*grin*) support libstdc++, you are more than welcome to try. - Configuring and building the library (see above) will still - require certain tools, however. Also keep in mind that - building libstdc++ does not imply that your compiler - will be able to use all of the features found in the - C++ Standard Library. -

-

Since the goal of ISO Standardization is for all C++ - implementations to be able to share code, the final libstdc++ - should, in theory, be usable under any ISO-compliant - compiler. It will still be targeted and optimized for - 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. -

-

Up through release 3.0.2 the tests performed were too general, and - this feature was disabled when it did not need to be. The most - commonly reported platform affected was Solaris. -

-

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 - macro _XOPEN_SOURCE. On GNU/Linux, the same happens - with _GNU_SOURCE. (This is not an exhaustive list; - other macros and other platforms are also affected.) -

-

These macros are typically used in C library headers, guarding new - versions of functions from their older versions. The C++ standard - library includes the C standard library, but it requires the C90 - version, which for backwards-compatibility reasons is often not the - default for many vendors. -

-

More to the point, the C++ standard requires behavior which is only - available on certain platforms after certain symbols are defined. - Usually the issue involves I/O-related typedefs. In order to - ensure correctness, the compiler simply predefines those symbols. -

-

Note that it's not enough to #define them only when the library is - being built (during installation). Since we don't have an 'export' - keyword, much of the library exists as headers, which means that - the symbols must also be defined as your programs are parsed and - compiled. -

-

To see which symbols are defined, look for CPLUSPLUS_CPP_SPEC in - the gcc config headers for your target (and try changing them to - see what happens when building complicated code). You can also run - "g++ -E -dM - < /dev/null" to display - a list of predefined macros for any particular installation. -

-

This has been discussed on the mailing lists - 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. - Here's a - link to the solution. -

- -
-

3.7 Threading is broken on i386

-

Support for atomic integer operations is/was broken on i386 - platforms. The assembly code accidentally used opcodes that are - only available on the i486 and later. So if you configured GCC - to target, for example, i386-linux, but actually used the programs - on an i686, then you would encounter no problems. Only when - actually running the code on a i386 will the problem appear. -

-

This is fixed in 3.2.2. -

- -
-

3.8 Recent GNU/Linux glibc required?

-

When running on GNU/Linux, libstdc++ 3.2.1 (shared library version - 5.0.1) and later uses localization and formatting code from the system - C library (glibc) version 2.2.5. That version of glibc is over a - year old and contains necessary bugfixes. Many GNU/Linux distros make - glibc version 2.3.x available now. -

-

The guideline is simple: the more recent the C++ library, the - more recent the C library. (This is also documented in the main - GCC installation instructions.) -

- -
-

3.9 Can't use wchar_t/wstring on FreeBSD

-

At the moment there are a few problems in FreeBSD's support for - wide character functions, and as a result the libstdc++ configury - decides that wchar_t support should be disabled. Once the underlying - problems are fixed in FreeBSD (soon), the library support will - automatically enable itself. -

-

You can fix the problems yourself, and learn more about the situation, - by reading - - this short thread ("_GLIBCPP_USE_WCHAR_T undefined in - FreeBSD's c++config.h?"). -

- -
-

3.10 MIPS atomic operations

-

The atomic locking routines for MIPS targets requires MIPS II - and later. A patch went in just after the 3.3 release to - make mips* use the generic implementation instead. You can also - configure for mipsel-elf as a workaround. -

-

mips*-*-linux* continues to use the MIPS II routines, and more - work in this area is expected. -

- -
-

4.0 Known Bugs and Non-Bugs

- Note that this section can get rapidly outdated -- such is the - nature of an open-source project. For the latest information, join - the mailing list or look through GCC bugzilla. - -

For 3.0.1, the most common "bug" is an apparently missing - "../" in include/Makefile, resulting in files - like gthr.h and gthr-single.h not being found. Please read - the configuration - instructions for GCC, - specifically the part about configuring in a separate build directory, - and how strongly recommended it is. Building in the source directory - is fragile, is rarely tested, and tends to break, as in this case. - This was fixed for 3.0.2. -

- -

For 3.1, the most common "bug" is a parse error when using - <fstream>, ending with a message, - "bits/basic_file.h:52: parse error before `{' - token." Please read - the installation instructions for - GCC, specifically the part about not installing newer versions on - top of older versions. If you install 3.1 over a 3.0.x release, then - the wrong basic_file.h header will be found (its location changed - between releases). -

- -

Please do not report these as bugs. We know about them. - Reporting this -- or any other problem that's already been fixed -- - hinders the development of GCC, because we have to take time to - respond to your report. Thank you. -

- -
-

4.1 What works already?

-

Short answer: Pretty much everything works except for some - corner cases. Also, localization is incomplete. For whether it works - well, or as you expect it to work, see 5.2. -

-

Long answer: See the implementation status pages for C++98, - TR1, and C++0x. -

- -
-

4.2 Bugs in gcc/g++ (not libstdc++)

-

This is by no means meant to be complete nor exhaustive, but - mentions some problems that users may encounter when building - or using libstdc++. If you are experiencing one of these - problems, you can find more information on the libstdc++ and - the GCC mailing lists. -

-

Before reporting a bug, examine the - bugs database with the - category set to "libstdc++". -

-
    -
  • Debugging is problematic, due to bugs in line-number generation - (mostly fixed in the compiler) and gdb lagging behind the - compiler (lack of personnel). We recommend configuring the - compiler using --with-dwarf2 if the DWARF2 - debugging format is not already the default on your platform. - Also, -changing your - GDB settings can have a profound effect on your C++ debugging - experiences. :-)
    • -
- -
-

4.3 Bugs in the C++ language/lib specification

-

Yes, unfortunately, there are some. In a - message - to the list, Nathan Myers announced that he has started a list of - problems in the ISO C++ Standard itself, especially with - regard to the chapters that concern the library. The list - itself is - posted on his - website. Developers who are having problems interpreting - the Standard may wish to consult his notes. -

-

For those people who are not part of the ISO Library Group - (i.e., nearly all of us needing to read this page in the first - place :-), a public list of the library defects is occasionally - published here. - 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 -

- 
-    #include <fstream>
-    ...
-    std::fstream  fs("a_file");
-    // .
-    // . do things with fs...
-    // .
-    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 in - 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. - Update: for GCC 4.0 we implemented the resolution - of DR #409 and open() now calls - clear() on success! -

-

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

-

For GCC versions 3.0 and 3.1 the libstdc++ header files are - installed in ${prefix}/include/g++-v3 (see the 'v'?). - Starting with version 3.2 the headers are installed in - ${prefix}/include/c++/${version} as this prevents - headers from previous versions being found by mistake. -

-

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

-

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 your library components
-    g++ -fPIC -c a.cc
-    g++ -fPIC -c b.cc
-    ...
-    g++ -fPIC -c z.cc
-
-    // create your library
-    g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o
-
-    // link the executable
-    g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl
-

"memory leaks" in containers - A few people have reported that the standard containers appear - to leak memory when tested with memory checkers such as - valgrind. - The library's default allocators keep free memory in a pool - for later reuse, rather than returning it to the OS. Although - this memory is always reachable by the library and is never - lost, memory debugging tools can report it as a leak. If you - want to test the library for memory leaks please read - Tips for memory leak hunting - first. -

- -

list::size() is O(n)! - See the Containers - chapter. -

-
-

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 - on submitting - patches that covers the procedure, but for libstdc++ you - should also send the patch to our mailing list in addition to - the GCC patches mailing list. The libstdc++ - contributors' page - also talks about how to submit patches. -

-

In addition to the description, the patch, and the ChangeLog - entry, it is a Good Thing if you can additionally create a small - test program to test for the presence of the bug that your - patch fixes. Bugs have a way of being reintroduced; if an old - bug creeps back in, it will be caught immediately by the - testsuite -- but only if such a test exists. -

- -
-

5.0 Miscellaneous

-

5.1 string::iterator is not char*; - vector<T>::iterator is not T*

-

If you have code that depends on container<T> iterators - being implemented as pointer-to-T, your code is broken. -

-

While there are arguments for iterators to be implemented in - that manner, A) they aren't very good ones in the long term, - and B) they were never guaranteed by the Standard anyway. The - type-safety achieved by making iterators a real class rather - than a typedef for T* outweighs nearly all opposing - arguments. -

-

Code which does assume that a vector iterator i - is a pointer can often be fixed by changing i in - certain expressions to &*i . Future revisions - of the Standard are expected to bless this usage for - vector<> (but not for basic_string<>). -

- -
-

5.2 What's next after libstdc++?

-

Hopefully, not much. The goal of libstdc++ is to produce - a fully-compliant, fully-portable Standard Library. After that, - we're mostly done: there won't be any more compliance - work to do. However: -

-
    -

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

    2. -

  2. Performance tuning. Lots of performance tuning was done for the - 3.x releases, including memory expansion in container classes and - buffer usage in synchronized stream objects. - Later performance-related work includes "move semantics" - for containers and (optional) non-reference-counted strings (which - can give performance benefits for multithreaded programs.) -

    3. -

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

    4. -

  4. 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 - libstdc++ if they seem to be "standard" enough. - (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. -

    5. -

  5. There is an effort underway to add significant extensions to - the standard library specification. The latest version of this effort is - described in - - The C++ Library Technical Report 1. - See 5.5. -

    6. -
-

This - question about the next libstdc++ prompted some brief but - interesting - speculation. -

- -
-

5.3 What about the STL from SGI?

-

The STL from SGI, - version 3.3, was the final merge of the STL codebase. The - code in libstdc++ contains many fixes and changes, and - the SGI code is no longer under active - development. We expect that no future merges will take place. -

-

In particular, string is not from SGI and makes no - use of their "rope" class (which is included as an - optional extension), nor is valarray and some others. - Classes like vector<> are, however we have - made significant changes to them since then. -

-

The FAQ for SGI's STL (one jump off of their main page) is - recommended reading. -

- -
-

5.4 Extensions and Backward Compatibility

-

Headers in the ext and backward - subdirectories should be referred to by their relative paths: - -

- 
-      #include <backward/hash_map>
-

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

- -

At this time most of the features of the SGI STL extension have been - replaced by standardized libraries. - In particular, the unordered_map and unordered_set containers of TR1 - are suitable replacement for the non-standard hash_map and hash_set - containers in the SGI STL. See 5.5 for more details. -

- -

The extensions are no longer in the global or std - namespaces, instead they are declared in the __gnu_cxx - namespace. For maximum portability, consider defining a namespace - alias to use to talk about extensions, e.g.: -

- 
-      #ifdef __GNUC__
-      #if __GNUC__ < 3
-        #include <hash_map.h>
-        namespace extension { using ::hash_map; }; // inherit globals
-      #else
-        #include <backward/hash_map>
-        #if __GNUC__ == 3 && __GNUC_MINOR__ == 0
-          namespace extension = std;               // GCC 3.0
-        #else
-          namespace extension = ::__gnu_cxx;       // GCC 3.1 and later
-        #endif
-      #endif
-      #else      // ...  there are other compilers, right?
-        namespace extension = std;
-      #endif
-
-      extension::hash_map<int,int> my_map;
-

This is a bit cleaner than defining typedefs for all the - instantiations you might need. -

-

Note: explicit template specializations must - be declared in the same namespace as the original template. - This means you cannot use a namespace alias when declaring - an explicit specialization. -

-

Extensions to the library have - their own page. -

- -
-

5.5 Does libstdc++ support TR1?

- -

The C++ Standard Library Technical Report adds many new features to - the library. The latest version of this effort is described in - - Technical Report 1. -

- -

libstdc++ strives to implement all of TR1. - An overview of the implementation status - is available. -

- -

Briefly, the features of TR1 and the current status are: -

- -

Reference_wrapper - Complete - - Useful to pass references to functions that take their parameters - by value. -

- -

Reference-counted smart pointers - Complete - - The shared_ptr and weak_ptr allow several object to know about a - pointer and whether it is valid. When the last reference to the - pointer is destroyed the pointer is freed. -

- -

Function objects - Complete - - Function return types (i.e., result_of), the functions template - mem_fn (a generalization of mem_fun and mem_fun_red), function - object binders (e.g., bind, a generalization of bind1st and bind2nd), - and polymorphic function wrappers (e.g, class template function). -

- -

Type traits - Complete - - The type_traits class gives templates the ability to probe - information about the input type and enable type-dependent logic - to be performed without the need of template specializations. -

- -

A random number engine - Complete - - This library contains random number generators with several different - choices of distribution. -

- -

Tuples - Complete - - The tuple class implements small heterogeneous arrays. This is an - enhanced pair. In fact, the standard pair is enhanced with a tuple - interface. -

- -

Fixed-size arrays - Complete - - The array class implements small fixed-sized arrays with container - semantics. -

- -

Unordered containers - Complete - - The unordered_set, unordered_map, unordered_multiset, and - unordered_multimap containers are hashed versions of the map, set, - multimap, and multiset containers respectively. These classes are - suitable replacements for the SGI STL hash_map and hash_set - extensions. -

- -

C99 compatibility - Under construction - - There are many features designed to minimize the divergence of the C - and the C++ languages. -

- -

Special functions - Complete - - Twenty-three mathematical functions familiar to physicists and - engineers are included: cylindrical and spherical Bessel and Neumann - functions, hypergeometric functions, Laguerre polynomials, Legendre - functions, elliptic integrals, exponential integrals and the Riemann - zeta function all for your computing pleasure. -

- -

A regular expression engine - This library provides for regular expression objects with traversal - of text with return of subexpressions. -

- -
-

5.6 Is libstdc++ thread-safe?

-

The library strives to be thread-safe when all of the following - conditions are met: -

-
    -
  • The system's libc is itself thread-safe,
    • -
  • The compiler in use reports a thread model other than 'single'. This can be tested via output from gcc -v. Multi-thread capable versions of gcc output something like this: -
    -%gcc -v
-Using built-in specs.
-...
-Thread model: posix
-gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
-
    - -

    Look for "Thread model" lines that aren't equal to "single."

    -
    • -
  • Requisite command-line flags are used for atomic operations and threading. Examples of this include -pthread and -march=native, although specifics vary depending on the host environment. See Machine Dependent Options.
    • -
  • An implementation of atomicity.h functions - exists for the architecture in question. See the internals documentation for more details.
    • - -
-

The user-code must guard against concurrent method calls which may - access any particular library object's state. Typically, the - application programmer may infer 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 () {
-       library_class_b *object_b = new library_class_b;
-       shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
-       shared_object_a.mutate ();          // must hold lock for shared_object_a
-     }
-
-     // 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, i.e., - treat library objects like any other shared resource. In general, - this requirement includes both read and write access to objects; - unless otherwise documented as safe, do not assume that two threads - may access a shared standard library object at the same time. -

-

See chapters 17 (library - introduction), 23 - (containers), and 27 (I/O) for - 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 - have not paid for the privilege of sitting on the committee and - sustained their two-meeting commitment for voting rights, may get a - copy of the standard from their respective national standards - organization. In the USA, this national standards organization is - ANSI and their website 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. -

-

Who is your country's member body? Visit the - ISO homepage and find out! -

-

The 2003 version of the standard (the 1998 version plus TC1) is - available in print, ISBN 0-470-84674-7. -

- -
-

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 - arguments are arranged on the call stack and/or in registers, and - how various types are arranged and padded in structs. A single CPU - design may suffer multiple ABIs designed by different development - tool vendors who made different choices, or even by the same vendor - for different target applications or compiler versions. In ideal - circumstances the CPU designer presents one ABI and all the OSes and - compilers use it. In practice every ABI omits details that compiler - implementers (consciously or accidentally) must choose for themselves. -

-

That ABI definition suffices for compilers to generate code so a - program can interact safely with an OS and its lowest-level libraries. - Users usually want an ABI to encompass more detail, allowing libraries - built with different compilers (or different releases of the same - compiler!) to be linked together. For C++, this includes many more - details than for C, and CPU designers (for good reasons elaborated - below) have not stepped up to publish C++ ABIs. The details include - virtual function implementation, struct inheritance layout, name - mangling, and exception handling. Such an ABI has been defined for - GNU C++, and is immediately useful for embedded work relying only on - a "free-standing implementation" that doesn't include (much - of) the standard library. It is a good basis for the work to come. -

-

A useful C++ ABI must also incorporate many details of the standard - library implementation. For a C ABI, the layouts of a few structs - (such as FILE, stat, jmpbuf, and the like) and a few macros suffice. - For C++, the details include the complete set of names of functions - and types used, the offsets of class members and virtual functions, - and the actual definitions of all inlines. C++ exposes many more - library details to the caller than C does. It makes defining - a complete ABI a much bigger undertaking, and requires not just - documenting library implementation details, but carefully designing - those details so that future bug fixes and optimizations don't - force breaking the ABI. -

-

There are ways to help isolate library implementation details from the - ABI, but they trade off against speed. Library details used in - inner loops (e.g., getchar) must be exposed and frozen for all - time, but many others may reasonably be kept hidden from user code, - so they may later be changed. Deciding which, and implementing - the decisions, must happen before you can reasonably document a - candidate C++ ABI that encompasses the standard library. -

- -
-

5.9 How do I make std::vector<T>::capacity() - == std::vector<T>::size()?

- -

The standard idiom for deallocating a std::vector<T>'s - unused memory is to create a temporary copy of the vector and swap their - contents, e.g. for std::vector<T> v -

- 
-     std::vector<T>(v).swap(v);
-
-

The copy will take O(n) time and the swap is constant time. -

-

See Shrink-to-fit strings for - a similar solution for strings. -

- - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - - diff --git a/libstdc++-v3/doc/html/index.html b/libstdc++-v3/doc/html/index.html new file mode 100644 index 000000000000..96ff103fb045 --- /dev/null +++ b/libstdc++-v3/doc/html/index.html @@ -0,0 +1,43 @@ + + + +The GNU C++ Library Documentation + + + + + + + +
+

The GNU C++ Library Documentation

+ +

Copyright 2008 FSF

+ +

+ Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License, Version 1.2 or any later version published by the + Free Software Foundation; with no Invariant Sections, with no + Front-Cover Texts, and with no Back-Cover Texts. +

+

+ This is the top level of the libstdc++ documentation tree. + The documentation is contained in three logically separate + documents, as listed in the following Table of Contents. +

+
+ + + + + + + diff --git a/libstdc++-v3/doc/html/install.html b/libstdc++-v3/doc/html/install.html deleted file mode 100644 index 3166ebc0a86f..000000000000 --- a/libstdc++-v3/doc/html/install.html +++ /dev/null @@ -1,240 +0,0 @@ - - - - - - - - - - libstdc++ Installation Instructions - - - - - -

Getting started: configure, build, install

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/install.html. -

- -

- To the libstdc++ homepage. -

- - - -
-

Contents

- -

Because libstdc++ is part of GCC, the primary source for - installation instructions is - the GCC install page. - Additional data is given here only where it applies to libstdc++. -

- - - -
- - - -

Tools you will need beforehand

-

The list of software needed to build the library is kept with the - rest of the compiler, at - - http://gcc.gnu.org/install/prerequisites.html. The same page - also lists the tools you will need if you wish to modify the source. -

- -

As of GCC 4.0.1 the minimum version of binutils required to build - libstdc++ is 2.15.90.0.1.1. You can get snapshots - (as well as releases) of binutils from - - ftp://sources.redhat.com/pub/binutils. - Older releases of libstdc++ do not require such a recent version, - but to take full advantage of useful space-saving features and - bug-fixes you should use a recent binutils if possible. - The configure process will automatically detect and use these - features if the underlying support is present. -

- -

Finally, a few system-specific requirements:

-
-
linux
- -
If gcc 3.1.0 or later on is being used on linux, an attempt - will be made to use "C" library functionality necessary for C++ - named locale support. For gcc 3.2.1 and later, this means that - glibc 2.2.5 or later is required and the "C" library de_DE locale - information must be installed. - -

- Note however that the sanity checks involving the de_DE locale are - skipped when an explicit --enable-clocale=gnu configure option is - used: only the basic checks are carried out, defending against - misconfigurations. -

- -

- If the 'gnu' locale model is being used, the following locales - are used and tested in the libstdc++ testsuites. The first column - is the name of the locale, the second is the character set it is - expected to use. -

-
-de_DE               ISO-8859-1
-de_DE@euro          ISO-8859-15
-en_HK               ISO-8859-1
-en_PH               ISO-8859-1
-en_US               ISO-8859-1
-en_US.ISO-8859-1    ISO-8859-1
-en_US.ISO-8859-15   ISO-8859-15
-en_US.UTF-8         UTF-8
-es_ES               ISO-8859-1
-es_MX               ISO-8859-1
-fr_FR               ISO-8859-1
-fr_FR@euro          ISO-8859-15
-is_IS               UTF-8
-it_IT               ISO-8859-1
-ja_JP.eucjp         EUC-JP
-se_NO.UTF-8         UTF-8
-ta_IN               UTF-8
-zh_TW               BIG5
-
-

Failure to have the underlying "C" library locale - information installed will mean that C++ named locales for the - above regions will not work: because of this, the libstdc++ - testsuite will skip the named locale tests. If this isn't an - issue, don't worry about it. If named locales are needed, the - underlying locale information must be installed. Note that - rebuilding libstdc++ after the "C" locales are installed is not - necessary. -

- -

To install support for locales, do only one of the following: -

- -
    -
  • install all locales -
      -
    • with RedHat Linux: -

      export LC_ALL=C

      -

      rpm -e glibc-common --nodeps

      -

      rpm -i --define "_install_langs all" - glibc-common-2.2.5-34.i386.rpm

      -
      • -
    • (instructions for other operating systems solicited)
      • -
    -
    • -
  • install just the necessary locales -
      -
    • with Debian Linux: -

      Add the above list, as shown, to the file - /etc/locale.gen

      -

      run /usr/sbin/locale-gen

      -
      • -
    • on most Unix-like operating systems: -

      localedef -i de_DE -f ISO-8859-1 de_DE

      -

      (repeat for each entry in the above list)

      -
      • -
    • (instructions for other operating systems solicited)
      • -
    -
    • -
-
-
- -
- -

Configuring

-

If you have never done this before, you should read the basic - GCC Installation - Instructions first. Read all of them. - Twice. -

-

When building libstdc++ you'll have to configure - the entire gccsrcdir directory. The full list of libstdc++ - specific configuration options, not dependent on the specific compiler - release being used, can be found here. -

-

Consider possibly using --enable-languages=c++ to save time by only - building the C++ language parts. -

- - 
-   cd gccbuilddir
-   gccsrcdir/configure --prefix=destdir --other-opts...
- - -
-

Using the library

-

Find the new library at runtime (shared linking only)

-

If you only built a static library (libstdc++.a), or if you - specified static linking, you don't have to worry about this. - But if you built a shared library (libstdc++.so) and linked - against it, then you will need to find that library when you - run the executable. -

-

Methods vary for different platforms and different styles, but - 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!
      • -
    -
    • -
-

Use the ldd(1) utility to show which library the system - thinks it will get at runtime. -

-

A libstdc++.la file is also installed, for use with Libtool. If - you use Libtool to create your executables, these details are - taken care of for you. -

- - - - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - - diff --git a/libstdc++-v3/doc/html/lib3styles.css b/libstdc++-v3/doc/html/lib3styles.css deleted file mode 100644 index ee88c366cd47..000000000000 --- a/libstdc++-v3/doc/html/lib3styles.css +++ /dev/null @@ -1,6 +0,0 @@ -.centered { text-align: center } -.tocheader { font-size: large } -.fineprint { font-size: x-small } -.larger { font-size: large } -BODY { background: #FFFFFF } -PRE { text-align: left ; margin-left: 1em } diff --git a/libstdc++-v3/doc/html/test.html b/libstdc++-v3/doc/html/test.html deleted file mode 100644 index 8a8694c2d6ef..000000000000 --- a/libstdc++-v3/doc/html/test.html +++ /dev/null @@ -1,722 +0,0 @@ - - - - - - - - - - libstdc++ Testing Instructions - - - - -

Testing Details

- -

- The latest version of this document is always available at - - http://gcc.gnu.org/onlinedocs/libstdc++/test.html. -

- -

- To the libstdc++ homepage. -

- - -
-

Contents

- - -
- - - -

Testsuite organization and naming conventions

-

- The directory libsrcdir/testsuite contains the - individual test cases organized in sub-directories corresponding - to chapters of the C++ standard (detailed below), the dejagnu - test harness support files, and sources to various testsuite - utilities that are packaged in a separate testing library. -

- -

All test cases for functionality required by the runtime - components of the C++ standard (ISO 14882) are files within the - following directories. -

- - 
-17_intro
-18_support
-19_diagnostics
-20_util
-21_strings
-22_locale
-23_containers
-25_algorithms
-26_numerics
-27_io
-
- -

- In addition, the following directories include test files: -

- - 
-tr1		  Tests for components as described by the Technical Report on Standard Library Extensions (TR1).
-backward	  Tests for backwards compatibility and deprecated features.
-demangle	  Tests for __cxa_demangle, the IA 64 C++ ABI demangler
-ext		  Tests for extensions.
-performance	  Tests for performance analysis, and performance regressions.
-thread		  Tests for threads.
-
- -

- Some directories don't have test files, but instead contain - auxiliary information (more information): -

- - 
-config		  Files for the dejagnu test harness.
-lib		  Files for the dejagnu test harness.
-libstdc++*     	  Files for the dejagnu test harness.
-data		  Sample text files for testing input and output.
-util		  Files for libtestc++, utilities and testing routines.
-
- -

- Within a directory that includes test files, there may be - additional subdirectories, or files. Originally, test cases - were appended to one file that represented a particular section - of the chapter under test, and was named accordingly. For - instance, to test items related to 21.3.6.1 - - basic_string::find [lib.string::find] in the standard, - the following was used: -

- 
-21_strings/find.cc
-
-

- However, that practice soon became a liability as the test cases - became huge and unwieldy, and testing new or extended - functionality (like wide characters or named locales) became - frustrating, leading to aggressive pruning of test cases on some - platforms that covered up implementation errors. Now, the test - suite has a policy of one file, one test case, which solves the - above issues and gives finer grained results and more manageable - error debugging. As an example, the test case quoted above - becomes: -

- 
-21_strings/basic_string/find/char/1.cc
-21_strings/basic_string/find/char/2.cc
-21_strings/basic_string/find/char/3.cc
-21_strings/basic_string/find/wchar_t/1.cc
-21_strings/basic_string/find/wchar_t/2.cc
-21_strings/basic_string/find/wchar_t/3.cc
-
- -

- All new tests should be written with the policy of one test - case, one file in mind. -

- -

- In addition, there are some special names and suffixes that are - used within the testsuite to designate particular kinds of - tests. -

- -
    -
  • - _xin.cc -

    - This test case expects some kind of interactive input in order - to finish or pass. At the moment, the interactive tests are not - run by default. Instead, they are run by hand, like: -

    - 
     
-g++ 27_io/objects/char/3_xin.cc
-cat 27_io/objects/char/3_xin.in | a.out
-
    -
    • -
  • - .in -

    - This file contains the expected input for the corresponding - _xin.cc test case. -

    -
    • -
  • - _neg.cc -

    - This test case is expected to fail: it's a negative test. At the - moment, these are almost always compile time errors. -

    -
    • -
  • - char -

    - This can either be a directory name or part of a longer file - name, and indicates that this file, or the files within this - directory are testing the char instantiation of a - template. -

    -
    • -
  • - wchar_t -

    - This can either be a directory name or part of a longer file - name, and indicates that this file, or the files within this - directory are testing the wchar_t instantiation of - a template. Some hosts do not support wchar_t - functionality, so for these targets, all of these tests will not - be run. -

    -
    • -
  • - thread -

    - This can either be a directory name or part of a longer file - name, and indicates that this file, or the files within this - directory are testing situations where multiple threads are - being used. -

    -
    • -
  • - performance -

    - This can either be an enclosing directory name or part of a - specific file name. This indicates a test that is used to - analyze runtime performance, for performance regression testing, - or for other optimization related analysis. At the moment, these - test cases are not run by default. -

    -
    • -
- -
-

Utilities: abi_check and libtestc++

-

- The testsuite directory also contains some files that implement - functionality that is intended to make writing test cases easier, - or to avoid duplication, or to provide error checking in a way that - is consistent across platforms and test harnesses. A stand-alone - executable, called abi_check, and a static library called - libtestc++ are constructed. Both of these items are not - installed, and only used during testing. -

- -

- These files include the following functionality: -

- -
    -
  • - testsuite_abi.h, - testsuite_abi.cc, - testsuite_abi_check.cc -

    - Creates the executable abi_check. - Used to check correctness of symbol versioning, visibility of - exported symbols, and compatibility on symbols in the shared - library, for hosts that support this feature. More information - can be found in the ABI documentation here -

    -
    • -
  • - testsuite_allocator.h, - testsuite_allocator.cc -

    - Contains specialized allocators that keep track of construction - and destruction. Also, support for overriding global new and - delete operators, including verification that new and delete - are called during execution, and that allocation over max_size - fails. -

    -
    • -
  • - testsuite_character.h -

    - Contains std::char_traits and - std::codecvt specializations for a user-defined - POD. -

    -
    • -
  • - testsuite_hooks.h, - testsuite_hooks.cc -

    - A large number of utilities, including: -

    -
      -
    • VERIFY
      • -
    • set_memory_limits
      • -
    • verify_demangle
      • -
    • run_tests_wrapped_locale
      • -
    • run_tests_wrapped_env
      • -
    • try_named_locale
      • -
    • try_mkfifo
      • -
    • func_callback
      • -
    • counter
      • -
    • copy_tracker
      • -
    • copy_constructor
      • -
    • assignment_operator
      • -
    • destructor
      • -
    • pod_char, pod_int and associated char_traits specializations
      • -
    -

    -
    • -
  • - testsuite_io.h -

    - Error, exception, and constraint checking for - std::streambuf, std::basic_stringbuf, std::basic_filebuf. -

    -
    • -
  • - testsuite_iterators.h -

    - Wrappers for various iterators. -

    -
    • -
  • - testsuite_performance.h -

    - A number of class abstractions for performance counters, and - reporting functions including: -

    -
      -
    • time_counter
      • -
    • resource_counter
      • -
    • report_performance
      • -
    -

    -
    • -
- -
-

How to write a new test case

- -

- The first step in making a new test case is to choose the correct - directory and file name, given the organization as previously - described. -

- -

- All files are copyright the FSF, and GPL'd: this is very - important. The first copyright year should correspond to the date - the file was checked in to SVN. -

- -

- As per the dejagnu instructions, always return 0 from main to - indicate success. -

- -

- A bunch of utility functions and classes have already been - abstracted out into the testsuite utility library, - libtestc++. To use this functionality, just include the - appropriate header file: the library or specific object files will - automatically be linked in as part of the testsuite run. -

- -

- For a test that needs to take advantage of the dejagnu test - harness, what follows below is a list of special keyword that - harness uses. Basically, a test case contains dg-keywords (see - dg.exp) indicating what to do and what kinds of behavior are to be - expected. New test cases should be written with the new style - DejaGnu framework in mind. -

- -

- To ease transition, here is the list of dg-keyword documentation - lifted from dg.exp. -

- -
-# The currently supported options are:
-#
-# dg-prms-id N
-#	set prms_id to N
-#
-# dg-options "options ..." [{ target selector }]
-#	specify special options to pass to the tool (eg: compiler)
-#
-# dg-do do-what-keyword [{ target/xfail selector }]
-#	`do-what-keyword' is tool specific and is passed unchanged to
-#	${tool}-dg-test.  An example is gcc where `keyword' can be any of:
-#	preprocess|compile|assemble|link|run
-#	and will do one of: produce a .i, produce a .s, produce a .o,
-#	produce an a.out, or produce an a.out and run it (the default is
-#	compile).
-#
-# dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate an error message <regexp> is expected on this line
-#	(the test fails if it doesn't occur)
-#	Linenum=0 for general tool messages (eg: -V arg missing).
-#	"." means the current line.
-#
-# dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate a warning message <regexp> is expected on this line
-#	(the test fails if it doesn't occur)
-#
-# dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate a bogus error message <regexp> use to occur here
-#	(the test fails if it does occur)
-#
-# dg-build regexp comment [{ target/xfail selector }]
-#	indicate the build use to fail for some reason
-#	(errors covered here include bad assembler generated, tool crashes,
-#	and link failures)
-#	(the test fails if it does occur)
-#
-# dg-excess-errors comment [{ target/xfail selector }]
-#	indicate excess errors are expected (any line)
-#	(this should only be used sparingly and temporarily)
-#
-# dg-output regexp [{ target selector }]
-#	indicate the expected output of the program is <regexp>
-#	(there may be multiple occurrences of this, they are concatenated)
-#
-# dg-final { tcl code }
-#	add some tcl code to be run at the end
-#	(there may be multiple occurrences of this, they are concatenated)
-#	(unbalanced braces must be \-escaped)
-#
-# "{ target selector }" is a list of expressions that determine whether the
-# test succeeds or fails for a particular target, or in some cases whether the
-# option applies for a particular target.  If the case of `dg-do' it specifies
-# whether the test case is even attempted on the specified target.
-#
-# The target selector is always optional.  The format is one of:
-#
-# { xfail *-*-* ... } - the test is expected to fail for the given targets
-# { target *-*-* ... } - the option only applies to the given targets
-#
-# At least one target must be specified, use *-*-* for "all targets".
-# At present it is not possible to specify both `xfail' and `target'.
-# "native" may be used in place of "*-*-*".
-
-Example 1: Testing compilation only
-// { dg-do compile }
-
-Example 2: Testing for expected warnings on line 36, which all targets fail
-// { dg-warning "string literals" "" { xfail *-*-* } 36
-
-Example 3: Testing for expected warnings on line 36
-// { dg-warning "string literals" "" { target *-*-* } 36
-
-Example 4: Testing for compilation errors on line 41
-// { dg-do compile }
-// { dg-error "no match for" "" { target *-*-* } 41 }
-
-Example 5: Testing with special command line settings, or without the
-use of pre-compiled headers, in particular the stdc++.h.gch file. Any
-options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set
-up in the normal.exp file.
-// { dg-options "-O0" { target *-*-* } }
-
- -

- More examples can be found in the libstdc++-v3/testsuite/*/*.cc files. -

- -
-

Options for running the tests

- -

There are several options for running tests, including testing - the regression tests, testing a subset of the regression tests, - testing the performance tests, testing just compilation, testing - installed tools, etc. In addition, there is a special rule for - checking the exported symbols of the shared library. -

- -

You can check the status of the build without installing it - using the dejagnu harness, much like the rest of the gcc tools.

- 
 make check
-

in the libbuilddir directory.

-

or

- 
 make check-target-libstdc++-v3
-

in the gccbuilddir directory.

- -

- These commands are functionally equivalent and will create a - 'testsuite' directory underneath libbuilddir containing - the results of the tests. Two results files will be generated: - libstdc++.sum, which is a PASS/FAIL summary for each - test, and libstdc++.log which is a log of the exact - command line passed to the compiler, the compiler output, and - the executable output (if any). -

- - -

-To debug the dejagnu test harness during runs, try invoking with a -specific argument to the variable RUNTESTFLAGS, as below. -

- -
-make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
-
-or -
-make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
-
- -

-To run a subset of the library tests, you will need to generate the -testsuite_files file by running make testsuite_files -in the libbuilddir/testsuite directory, described below. -Edit the file to remove the tests you don't want and then run the -testsuite as normal. -

- - -

-There are two ways to run on a simulator: set up DEJAGNU to point to a -specially crafted site.exp, or pass down --target_board flags. -

-Example flags to pass down for various embedded builds are as follows: -
---target=powerpc-eabism (libgloss/sim)
-make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
-
---target=calmrisc32 (libgloss/sid)
-make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
-
---target=xscale-elf (newlib/sim)
-make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
-
- -

Also, here is an example of how to run the libstdc++ testsuite for a -multilibed build directory with different ABI settings: -

-
-make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
-
- -

-You can run the tests with a compiler and library that have already -been installed. Make sure that the compiler (e.g., g++) -is in your PATH. If you are using shared libraries, then -you must also ensure that the directory containing the shared version -of libstdc++ is in your LD_LIBRARY_PATH, or equivalent. -If your GCC source tree is at /path/to/gcc, then you can -run the tests as follows: -

-
-runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
-
-

-The testsuite will create a number of files in the directory in which you -run this command,. Some of those files might use the same name as -files created by other testsuites (like the ones for GCC and G++), so -you should not try to run all the testsuites in parallel from the same -directory. -

- -

In addition, there are some testing options that are mostly of - interest to library maintainers and system integrators. As such, - these tests may not work on all cpu and host combinations, and may need to - be executed in the libbuilddir/testsuite directory. These options - include, but are not necessarily limited to, the following: -

- - 
-   make testsuite_files
-

- Five files are generated that determine what test files - are run. These files are: -

-
    -
  • - testsuite_files -

    This is a list of all the test cases that will be run. Each - test case is on a separate line, given with an absolute path - from the libsrcdir/testsuite directory. -

    -
    • - -
  • - testsuite_files_interactive -

    This is a list of all the interactive test cases, using the - same format as the file list above. These tests are not run by default. -

    -
    • - -
  • - testsuite_files_performance -

    This is a list of all the performance test cases, using the - same format as the file list above. These tests are not run by default. -

    -
    • - -
  • - testsuite_thread -

    This file indicates that the host system can run tests which - incolved multiple threads. -

    -
    • - -
  • - testsuite_wchar_t -

    This file indicates that the host system can run the wchar_t - tests, and corresponds to the macro definition - _GLIBCXX_USE_WCHAR_T in the file c++config.h. -

    -
    • -
- - 
-   make check-abi
-

The library ABI can be tested. This involves testing the shared - library against an ABI-defining previous version of symbol exports.

- - 
-   make check-compile
-

This rule compiles, but does not link or execute, the - testsuite_files test cases and displays the output on stdout.

- - 
-   make check-performance
-

This rule runs through the testsuite_files_performance - test cases and collects information for performance analysis and - can be used to spot performance regressions. Various timing - information is collected, as well as number of hard page faults, - and memory used. This is not run by default, and the implementation - is in flux. -

- -

- We are interested in any strange failures of the - testsuite; please see FAQ 2.4 - for which files to examine. -

- -
-

Running debug-mode tests

-

To run the libstdc++ test suite under the debug mode, - edit libstdc++-v3/scripts/testsuite_flags to add the - compile-time flag -D_GLIBCXX_DEBUG to the result - printed by the --build-cxx option. Additionally, add - the -D_GLIBCXX_DEBUG_PEDANTIC flag to turn on pedantic - checking. The libstdc++ test suite should produce precisely the same - results under debug mode that it does under release mode: any - deviation indicates an error in either the library or the test - suite.

- -
-

Future

- -

-Shared runs need to be implemented, for targets that support shared libraries. -

- -

-Diffing of expected output to standard streams needs to be finished off. -

- -

-The V3 testing framework supports, or will eventually support, -additional keywords for the purpose of easing the job of writing -test cases. All V3-keywords are of the form @xxx@. -Currently plans for supported keywords include: -

- -
-
@require@ <files>
-
-

- The existence of <files> is essential for the test to complete - successfully. For example, a test case foo.C using bar.baz as - input file could say -

- 
-	    // @require@ bar.baz
-

- The special variable % stands for the rootname, e.g. the - file-name without its `.C' extension. Example of use (taken - verbatim from 27_io/filebuf.cc) -

- 
-	   // @require@ %-*.tst %-*.txt
-
-
@diff@ <first-list> <second-list>
-
-

- After the test case compiles and ran successfully, diff - <first-list> against <second-list>, these lists should - have the same length. The test fails if diff returns non-zero a - pair of files. -

-
-
- -
-

DejaGNU internals

- -

This is information for those looking at making changes to the testsuite -structure, and/or needing to trace dejagnu's actions with --verbose. This -will not be useful to people who are "merely" adding new tests to the existing -structure. -

- -

The first key point when working with dejagnu is the idea of a "tool". -Files, directories, and functions are all implicitly used when they are -named after the tool in use. Here, the tool will always be "libstdc++". -

- -

The lib subdir contains support routines. The -lib/libstdc++.exp file ("support library") is loaded -automagically, and must explicitly load the others. For example, files can -be copied from the core compiler's support directory into lib. -

- -

Some routines in lib/libstdc++.exp are callbacks, some are -our own. Callbacks must be prefixed with the name of the tool. To easily -distinguish the others, by convention our own routines are named "v3-*". -

- -

The next key point when working with dejagnu is "test files". Any -directory whose name starts with the tool name will be searched for test files. -(We have only one.) In those directories, any .exp file is -considered a test file, and will be run in turn. Our main test file is called -normal.exp; it runs all the tests in testsuite_files using the -callbacks loaded from the support library. -

- -

The config directory is searched for any particular "target -board" information unique to this library. This is currently unused and sets -only default variables. -

- - - - -
-

-See license.html for copying conditions. -Comments and suggestions are welcome, and may be sent to -the libstdc++ mailing list. -

- - - - -- 2.47.2