<?xml version='1.0'?><!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN""http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ ]><appendix id="appendix.contrib" xreflabel="Contributing"><?dbhtml filename="appendix_contributing.html"?><appendixinfo><keywordset><keyword>ISO C++</keyword><keyword>library</keyword></keywordset></appendixinfo><title>Contributing</title><para>The GNU C++ Library follows an open development model. Activecontributors are assigned maintainer-ship responsibility, and givenwrite access to the source repository. First time contributorsshould follow this procedure:</para><sect1 id="contrib.list" xreflabel="Contributor Checklist"><title>Contributor Checklist</title><sect2 id="list.reading" xreflabel="list.reading"><title>Reading</title><itemizedlist><listitem><para>Get and read the relevant sections of the C++ languagespecification. Copies of the full ISO 14882 standard areavailable on line via the ISO mirror site for committeemembers. Non-members, or those who have not paid for theprivilege of sitting on the committee and sustained theirtwo meeting commitment for voting rights, may get a copy ofthe standard from their respective national standardsorganization. In the USA, this national standardsorganization is ANSI and their web-site is right<ulink url="http://www.ansi.org">here.</ulink>(And if you've already registered with them, clicking this link will take you to directly to the place where you can<ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink></para></listitem><listitem><para>The library working group bugs, and known defects, canbe obtained here:<ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink></para></listitem><listitem><para>The newsgroup dedicated to standardization issues iscomp.std.c++: this FAQ for this group is quite useful andcan befound <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html">here </ulink>.</para></listitem><listitem><para>Perusethe <ulink url="http://www.gnu.org/prep/standards_toc.html">GNUCoding Standards</ulink>, and chuckle when you hit the partabout <quote>Using Languages Other Than C</quote>.</para></listitem><listitem><para>Be familiar with the extensions that preceded thesegeneral GNU rules. These style issues for libstdc++ can befound <link linkend="contrib.coding_style">here</link>.</para></listitem><listitem><para>And last but certainly not least, read thelibrary-specific informationfound <link linkend="appendix.porting"> here</link>.</para></listitem></itemizedlist></sect2><sect2 id="list.copyright" xreflabel="list.copyright"><title>Assignment</title><para>Small changes can be accepted without a copyright assignment form onfile. New code and additions to the library need completed copyrightassignment form on file at the FSF. Note: your employer may be requiredto fill out appropriate disclaimer forms as well.</para><para>Historically, the libstdc++ assignment form added the followingquestion:</para><para><quote>Which Belgian comic book character is better, Tintin or Asterix, andwhy?</quote></para><para>While not strictly necessary, humoring the maintainers and answeringthis question would be appreciated.</para><para>For more information about getting a copyright assignment, please see<ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">LegalMatters</ulink>.</para><para>Please contact Benjamin Kosnik at<email>bkoz+assign@redhat.com</email> if you are confusedabout the assignment or have general licensing questions. Whenrequesting an assignment form from<email>mailto:assign@gnu.org</email>, please cc the libstdc++maintainer above so that progress can be monitored.</para></sect2><sect2 id="list.getting" xreflabel="list.getting"><title>Getting Sources</title><para><ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access(look for "Write after approval")</ulink></para></sect2><sect2 id="list.patches" xreflabel="list.patches"><title>Submitting Patches</title><para>Every patch must have several pieces of information before it can beproperly evaluated. Ideally (and to ensure the fastest possibleresponse from the maintainers) it would have all of these pieces:</para><itemizedlist><listitem><para>A description of the bug and how your patch fixes thisbug. For new features a description of the feature and yourimplementation.</para></listitem><listitem><para>A ChangeLog entry as plain text; see the variousChangeLog files for format and content. If using you areusing emacs as your editor, simply position the insertionpoint at the beginning of your change and hit CX-4a to bringup the appropriate ChangeLog entry. See--magic! Similarfunctionality also exists for vi.</para></listitem><listitem><para>A testsuite submission or sample program that willeasily and simply show the existing error or test newfunctionality.</para></listitem><listitem><para>The patch itself. If you are accessing the SVNrepository use <command>svn update; svn diff NEW</command>;else, use <command>diff -cp OLD NEW</command> ... If yourversion of diff does not support these options, then get thelatest version of GNUdiff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVNTricks</ulink> wiki page has information on customising theoutput of <code>svn diff</code>.</para></listitem><listitem><para>When you have all these pieces, bundle them up in amail message and send it to libstdc++@gcc.gnu.org. Allpatches and related discussion should be sent to thelibstdc++ mailing list.</para></listitem></itemizedlist></sect2></sect1><sect1 id="contrib.organization" xreflabel="Source Organization"><title>Directory Layout and Source Conventions</title><para>The unpacked source directory of libstdc++ contains the filesneeded to create the GNU C++ Library.</para><literallayout>It has subdirectories:docFiles in HTML and text format that document usage, quirks of theimplementation, and contributor checklists.includeAll header files for the C++ library are within this directory,modulo specific runtime-related files that are in the libsupc++directory.include/stdFiles meant to be found by #include <name> directives instandard-conforming user programs.include/cHeaders intended to directly include standard C headers.[NB: this can be enabled via --enable-cheaders=c]include/c_globalHeaders intended to include standard C headers inthe global namespace, and put select names into the std::namespace. [NB: this is the default, and is the same as--enable-cheaders=c_global]include/c_stdHeaders intended to include standard C headersalready in namespace std, and put select names into the std::namespace. [NB: this is the same as --enable-cheaders=c_std]include/bitsFiles included by standard headers and by other files inthe bits directory.include/backwardHeaders provided for backward compatibility, such as <iostream.h>.They are not used in this library.include/extHeaders that define extensions to the standard library. Nostandard header refers to any of them.scriptsScripts that are used during the configure, build, make, or testprocess.srcFiles that are used in constructing the library, but are notinstalled.testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*]Test programs are here, and may be used to begin to exercise thelibrary. Support for "make check" and "make check-install" iscomplete, and runs through all the subdirectories here when thiscommand is issued from the build directory. Please note that"make check" requires DejaGNU 1.4 or later to be installed. Pleasenote that "make check-script" calls the script mkcheck, whichrequires bash, and which may need the paths to bash adjusted towork properly, as /bin/bash is assumed.Other subdirectories contain variant versions of certain filesthat are meant to be copied or linked by the configure script.Currently these are:config/abiconfig/cpuconfig/ioconfig/localeconfig/osIn addition, two subdirectories are convenience libraries:libmathSupport routines needed for C++ math. Only needed if theunderlying "C" implementation is non-existent, in particularrequired or optimal long double, long long, and C99 functionality.libsupc++Contains the runtime library for C++, including exceptionhandling and memory allocation and deallocation, RTTI, terminatehandlers, etc.Note that glibc also has a bits/ subdirectory. We will eitherneed to be careful not to collide with names in its bits/directory; or rename bits to (e.g.) cppbits/.In files throughout the system, lines marked with an "XXX" indicatea bug or incompletely-implemented feature. Lines marked "XXX MT"indicate a place that may require attention for multi-thread safety.</literallayout></sect1><sect1 id="contrib.coding_style" xreflabel="Coding Style"><title>Coding Style</title><para></para><sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad"><title>Bad Identifiers</title><para>Identifiers that conflict and should be avoided.</para><literallayout>This is the list of names <quote>reserved to theimplementation</quote> that have been claimed by certaincompilers and system headers of interest, and should not be usedin the library. It will grow, of course. We generally areinterested in names that are not all-caps, except for those like"_T"For Solaris:_B_C_L_N_P_S_U_X_E1.._E24Irix adds:_A_GMS adds:_TBSD 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 oldname-mangling; in G++ 3.0 and higher a different name-mangling isused. In addition, many of the bugs relating to G++ interpretingthese names as operators have been fixed.]The full set of __* identifiers (combined from gcc/cp/lex.c andgcc/cplus-dem.c) that are either old or new, but are definitelyrecognized 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__vnSGI 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</literallayout></sect2><sect2 id="coding_style.example" xreflabel="coding_style.example"><title>By Example</title><literallayout>This library is written to appropriate C++ coding standards. As such,it is intended to precede the recommendations of the GNU CodingStandard, which can be referenced in full here:http://www.gnu.org/prep/standards/standards.html#FormattingThe rest of this is also interesting reading, but skip the "DesignAdvice" part.The GCC coding conventions are here, and are also useful:http://gcc.gnu.org/codingconventions.htmlIn addition, because it doesn't seem to be stated explicitly anywhereelse, there is an 80 column source limit.ChangeLog entries for member functions should use theclassname::member function name syntax as follows:1999-04-15 Dennis Ritchie <dr@att.com>* 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 referenceschar* p = "flop";char& c = *p;-NOT-char *p = "flop"; // wrongchar &c = *p; // wrongReason: In C++, definitions are mixed with executable code. Here,p is being initialized, not *p. This is near-universalpractice among C++ programmers; it is normal for C hackersto switch spontaneously as they gain experience.02. Operator names and parenthesesoperator==(type)-NOT-operator == (type) // wrongReason: The == is part of the function name. Separatingit makes the declaration look like an expression.03. Function names and parenthesesvoid mangle()-NOT-void mangle () // wrongReason: no space before parentheses (except after a control-flowkeyword) is near-universal practice for C++. It identifies theparentheses as the function-call operator or declarator, asopposed to an expression or other overloaded use of parentheses.04. Template function indentationtemplate<typename T>voidtemplate_function(args){ }-NOT-template<class T>void template_function(args) {};Reason: In class definitions, without indentation whitespace isneeded both above and below the declaration to distinguishit visually from other members. (Also, re: "typename"rather than "class".) T often could be int, which isnot a class. ("class", here, is an anachronism.)05. Template class indentationtemplate<typename _CharT, typename _Traits>class basic_ios : public ios_base{public:// Types:};-NOT-template<class _CharT, class _Traits>class basic_ios : public ios_base{public:// Types:};-NOT-template<class _CharT, class _Traits>class basic_ios : public ios_base{public:// Types:};06. Enumeratorsenum{space = _ISspace,print = _ISprint,cntrl = _IScntrl};-NOT-enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };07. Member initialization listsAll 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 blockstry{//}catch (...){//}-NOT-try {//} catch(...) {//}09. Member functions declarations and definitionsKeywords such as extern, static, export, explicit, inline, etcgo on the line above the function name. Thusvirtual intfoo()-NOT-virtual int foo()Reason: GNU coding conventions dictate return types for functionsare on a separate line than the function name and parameter listfor definitions. For C++, where we have member functions that canbe either inline definitions or declarations, keeping to thisstandard allows all member function names for a given class to bealigned to the same margin, increasing readability.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. Namespacesnamespace std{blah blah blah;} // namespace std-NOT-namespace std {blah blah blah;} // namespace std12. Spacing under protected and private in class declarations:space above, none belowi.e.public:int foo;-NOT-public:int foo;13. Spacing WRT return statements.no extra spacing before returns, no parenthesisi.e.}return __ret;-NOT-}return __ret;-NOT-}return (__ret);14. Location of global variables.All global variables of class type, whether in the "user visible"space (e.g., cin) or the implementation namespace, must be definedas a character array with the appropriate alignment and then laterre-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 suchvariables should be contained in that file, for simplicity.15. Exception abstractionsUse the exception abstractions found in functexcept.h, which allowC++ programmers to use this library with -fno-exceptions. (Even ifthat is rarely advisable, it's a necessary evil for backwardscompatibility.)16. Exception error messagesAll start with the name of the function where the exception isthrown, 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 thedefault terminate handler, by putting location info into theexception string, a very useful error message is printed out foruncaught exceptions. So useful, in fact, that non-programmers cangive useful error messages, and programmers can intelligentlyspeculate 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++ codingstyles. The GNU C usages will be combed out gradually.Name patterns:For nonstandard names appearing in Standard headers, we are constrainedto use names that begin with underscores. This is called "uglification".The convention is:Local and argument names: __[a-z].*Examples: __count __ix __s1Type names and template formal-argument names: _[A-Z][^_].*Examples: _Helper _CharT _NMember data and function names: _M_.*Examples: _M_num_elements _M_initialize ()Static data members, constants, and enumerations: _S_.*Examples: _S_max_elements _S_default_valueDon'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 nameunmanglers on some targets. Also, never use "__[0-9]", same reason.--------------------------[BY EXAMPLE]#ifndef _HEADER_#define _HEADER_ 1namespace std{class gribble{public:gribble() throw();gribble(const gribble&);explicitgribble(int __howmany);gribble&operator=(const gribble&);virtual~gribble() throw ();// Start with a capital letter, end with a period.inline voidpublic_member(const char* __arg) const;// In-class function definitions should be restricted to one-liners.intone_line() { return 0 }inttwo_lines(const char* arg){ return strchr(arg, 'a'); }inline intthree_lines(); // inline, but defined below.// Note indentation.template<typename _Formal_argument>voidpublic_template() const throw();template<typename _Iterator>voidother_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_LONGLONGextern 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 intgribble::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<typename T> // notice: "typename", not "class", no spacelong_return_value_type<with_many, args>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 intgribble::three_lines(){// doesn't fit in one line.}} // namespace std</literallayout></sect2></sect1><sect1 id="contrib.doc_style" xreflabel="Documentation Style"><title>Documentation Style</title><sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen"><title>Doxygen</title><sect3 id="doxygen.prereq" xreflabel="doxygen.prereq"><title>Prerequisites</title><para>Prerequisite tools are Bash 2.x,<ulink url="http://www.doxygen.org/">Doxygen</ulink>, andthe <ulink url="http://www.gnu.org/software/coreutils/">GNUcoreutils</ulink>. (GNU versions of find, xargs, and possiblysed and grep are used, just because the GNU versions makethings very easy.)</para><para>To generate the pretty pictures and hierarchygraphs, the<ulink url="http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink>package will need to be installed.</para></sect3><sect3 id="doxygen.rules" xreflabel="doxygen.rules"><title>Generating the Doxygen Files</title><para>The Makefile rules</para><screen><userinput>make doc-html-doxygen</userinput></screen><para>and</para><screen><userinput>make doc-xml-doxygen</userinput></screen><para>and</para><screen><userinput>make doc-man-doxygen</userinput></screen><para>in the libstdc++ build directory generate the HTML docs, theXML docs, and the man pages.</para><para>Careful observers will see that the Makefile rules simply calla script from the source tree, <filename>run_doxygen</filename>, whichdoes the actual work of running Doxygen and then (mostimportantly) massaging the output files. If for some reasonyou prefer to not go through the Makefile, you can call thisscript directly. (Start by passing <literal>--help</literal>.)</para><para>If you wish to tweak the Doxygen settings, do so by editing<filename>doc/doxygen/user.cfg.in</filename>. Notes to fellowlibrary hackers are written in triple-# comments.</para></sect3><sect3 id="doxygen.markup" xreflabel="doxygen.markup"><title>Markup</title><para>In general, libstdc++ files should be formatted according tothe rules found in the<link linkend="contrib.coding_style">Coding Standard</link>. Beforeany doxygen-specific formatting tweaks are made, please try tomake sure that the initial formatting is sound.</para><para>Adding Doxygen markup to a file (informally called<quote>doxygenating</quote>) is very simple. The Doxygen manual can befound<ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>.We try to use a very-recent version of Doxygen.</para><para>For classes, use<classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>and <classname>std::pair</classname> as examples. Forfunctions, see their member functions, and the free functionsin <filename>stl_algobase.h</filename>. Member functions ofother container-like types should read similarly to thesemember functions.</para><para>These points accompany the first list in section 3.1 of theDoxygen manual:</para><orderedlist><listitem><para>Use the Javadoc style...</para></listitem><listitem><para>...not the Qt style. The intermediate *'s are preferred.</para></listitem><listitem><para>Use the triple-slash style only for one-line comments (the<quote>brief</quote> mode). Very recent versions of Doxygen permitfull-mode comments in triple-slash blocks, but theformatting still comes out wonky.</para></listitem><listitem><para>This is disgusting. Don't do this.</para></listitem></orderedlist><para>Use the @-style of commands, not the !-style. Please becareful about whitespace in your markup comments. Most of thetime it doesn't matter; doxygen absorbs most whitespace, andboth HTML and *roff are agnostic about whitespace. However,in <pre> blocks and @code/@endcode sections, spacing canhave <quote>interesting</quote> effects.</para><para>Use either kind of grouping, asappropriate. <filename>doxygroups.cc</filename> exists for thispurpose. See <filename>stl_iterator.h</filename> for a good exampleof the <quote>other</quote> kind of grouping.</para><para>Please use markup tags like @p and @a when referring to thingssuch as the names of function parameters. Use @e for emphasiswhen necessary. Use @c to refer to other standard names.(Examples of all these abound in the present code.)</para></sect3></sect2><sect2 id="doc_style.docbook" xreflabel="doc_style.docbook"><title>Docbook</title><sect3 id="docbook.prereq" xreflabel="docbook.prereq"><title>Prerequisites</title><para>Editing the DocBook sources requires an XML editor. Manyexist: some notable optionsinclude <command>emacs</command>, <application>Kate</application>,or <application>Conglomerate</application>.</para><para>Some editors support special <quote>XML Validation</quote>modes that can validate the file as it isproduced. Recommended is the <command>nXML Mode</command>for <command>emacs</command>.</para><para>Besides an editor, additional DocBook files and XML tools arealso required.</para><para>Access to the DocBook stylesheets and DTD is required. Thestylesheets are usually packaged by vendor, in somethinglike <filename>docbook-style-xsl</filename>. The installationdirectory for this package corresponds tothe <literal>XSL_STYLE_DIR</literal>in <filename>doc/Makefile.am</filename> and defaultsto <filename class="directory">/usr/share/sgml/docbook/xsl-stylesheets</filename>.</para><para>For processing XML, an XML processor and some stylesheets are necessary. Defaults are <command>xsltproc</command>provided by <filename>libxslt</filename>.</para><para>For validating the XML document, you'll needsomething like <command>xmllint</command> and access to theDocBook DTD. These are providedby a vendor package like <filename>lixml2</filename>.</para><para>For PDF output, something that transforms valid XML to PDF isrequired. Possible solutions include <command>xmlto</command>,<ulink url="http://xmlgraphics.apache.org/fop/">ApacheFOP</ulink>, or <command>prince</command>. Other options arelisted on the DocBook web <ulinkurl="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Pleaseconsult the <email>libstdc++@gcc.gnu.org</email> list whenpreparing printed manuals for current best practice and suggestions.</para><para>Make sure that the XML documentation and markup is valid forany change. This can be done easily, with the validation rulesin the <filename>Makefile</filename>, which is equivalent to doing:</para><screen><userinput>xmllint --noout --valid <filename>xml/index.xml</filename></userinput></screen></sect3><sect3 id="docbook.rules" xreflabel="docbook.rules"><title>Generating the DocBook Files</title><para>The Makefile rules</para><screen><userinput>make doc-html</userinput></screen><para>and</para><screen><userinput>make doc-pdf</userinput></screen><para>and</para><screen><userinput>make doc-xml-single</userinput></screen><para>and</para><screen><userinput>make doc-xml-validate</userinput></screen><para>in the libstdc++ build directory result respectively in thefollowing: the generation of an HTML version of all thedocumentation, a PDF version of the same, a single XMLdocument, and the results of validating the XML document.</para></sect3><sect3 id="docbook.examples" xreflabel="docbook.examples"><title>File Organization and Basics</title><literallayout><emphasis>Which files are important</emphasis>All Docbook files are in the directorylibstdc++-v3/doc/xmlInside this directory, the files of importance:spine.xml - index to documentation setmanual/spine.xml - index to manualmanual/*.xml - individual chapters and sections of the manualfaq.xml - index to FAQapi.xml - index to source level / APIAll *.txml files are template xml files, i.e., otherwise empty files withthe correct structure, suitable for filling in with new information.<emphasis>Canonical Writing Style</emphasis>class templatefunction templatemember function template(via C++ Templates, Vandevoorde)class in namespace std: allocator, not std::allocatorheader file: iostream, not <iostream><emphasis>General structure</emphasis><set><book></book><book><chapter></chapter></book><book><part><chapter><section></section><sect1></sect1><sect1><sect2></sect2></sect1></chapter><chapter></chapter></part></book></set></literallayout></sect3><sect3 id="docbook.markup" xreflabel="docbook.markup"><title>Markup By Example</title><literallayout>HTML to XML rough equivalents<p> <para><pre> <computeroutput><pre> <programlisting><pre> <literallayout><ul> <itemizedlist><ol> <orderedlist><il> <listitem><dl> <variablelist><varlistentry><dt> <term></dt> </term><dd> <listitem></dt> </listitem></varlistentry><a href <ulink url<code> <literal><code> <programlisting><strong> <emphasis><em> <emphasis>" <quote>ctype.h <filename class="headerfile"></filename>build_dir <filename class="directory">path_to_build_dir</filename>Finer gradations of <code><classname> <classname>string</classname><classname>vector<></classname><function>fs.clear()</function><structname><function> <function>clear()</function><type> <type>long long</type><varname> <varname>fs</varname><literal> <literal>-Weffc++</literal><literal>rel_ops</literal><constant> <constant>_GNU_SOURCE</constant><constant>3.0</constant><filename><command> <command>g++</command><errortext> <errortext>foo Concept </errortext></literallayout></sect3></sect2></sect1><sect1 id="contrib.design_notes" xreflabel="Design Notes"><title>Design Notes</title><para></para><literallayout>The Library-----------This paper is covers two major areas:- Features and policies not mentioned in the standard thatthe quality of the library implementation depends on, includingextensions and "implementation-defined" features;- Plans for required but unimplemented library features andoptimizations to them.Overhead--------The standard defines a large library, much larger than the standardC library. A naive implementation would suffer substantial overheadin compile time, executable size, and speed, rendering it unusablein many (particularly embedded) applications. The alternative demandscare in construction, and some compiler support, but there is noneed for library subsets.What are the sources of this overhead? There are four main causes:- The library is specified almost entirely as templates, whichwith current compilers must be included in-line, resulting invery slow builds as tens or hundreds of thousands of linesof 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 inporting. Iostream/locale is (or will be) as large again.- The library is very flexible, specifying a multitude of hookswhere users can insert their own code in place of defaults.When these hooks are not used, any time and code expended tosupport that flexibility is wasted.- Templates are often described as causing to "code bloat". Inpractice, this refers (when it refers to anything real) to severalindependent processes. First, when a class template is manuallyinstantiated in its entirely, current compilers place the definitionsfor all members in a single object file, so that a program linkingto one member gets definitions of all. Second, template functionswhich do not actually depend on the template argument are, undercurrent compilers, generated anew for each instantiation, ratherthan being shared with other instantiations. Third, some of theflexibility mentioned above comes from virtual functions (both inregular classes and template classes) which current linkers addto 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 andcode space cost to handle the possibility of exceptions even whenthey are not used. Under the new ABI (accessed with -fnew-abi),there is a space overhead and a small reduction in code efficiencyresulting from lost optimization opportunities associated withnon-local branches associated with exceptions.What can be done to eliminate this overhead? A variety of codingtechniques, and compiler, linker and library improvements andextensions 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 archivesallows us to avoid generating and optimizing template instantiationsin each compilation unit which uses them. However, the number of suchinstantiations that are useful to provide is limited, and anyway thisis 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 compilerimprovements. One approach is some variation on the techniquespreviously marketed as "pre-compiled headers", now standardized assupport for the "export" keyword. "Exported" template definitionscan be placed (once) in a "repository" -- really just a library, butof template definitions rather than object code -- to be drawn uponat link time when an instantiation is needed, rather than placed inheader files to be parsed along with every compilation unit.Until "export" is implemented we can put some of the lengthy templatedefinitions in #if guards or alternative headers so that users can skipover the full definitions when they need only the ready-instantiatedspecializations.To be precise, this means that certain headers which definetemplates which users normally use only for certain argumentscan be instrumented to avoid exposing the template definitionsto the compiler unless a macro is defined. For example, in<string>, we might have:template <class _CharT, ... > class basic_string {... // member declarations};... // operator declarations#ifdef _STRICT_ISO_# if _G_NO_TEMPLATE_EXPORT# include <bits/std_locale.h> // headers needed by definitions# ...# include <bits/string.tcc> // member and global template definitions.# endif#endifUsers who compile without specifying a strict-ISO-conforming flagwould not see many of the template definitions they now see, and relyinstead on ready-instantiated specializations in the library. Thistechnique would be useful for the following substantial components:string, locale/iostreams, valarray. It would *not* be useful orusable with the following: containers, algorithms, iterators,allocator. Since these constitute a large (though decreasing)fraction of the library, the benefit the technique offers islimited.The language specifies the semantics of the "export" keyword, butthe gcc compiler does not yet support it. When it does, problemswith large template inclusions can largely disappear, given someminor library reorganization, along with the need for the apparatusdescribed above.Overhead: Flexibility Cost--------------------------The library offers many places where users can specify operationsto be performed by the library in place of defaults. Sometimesthis seems to require that the library use a more-roundabout, andpossibly slower, way to accomplish the default requirements thanwould be used otherwise.The primary protection against this overhead is thorough compileroptimization, to crush out layers of inline function interfaces.Kuck & Associates has demonstrated the practicality of this kindof optimization.The second line of defense against this overhead is explicitspecialization. By defining helper function templates, and writingspecialized code for the default case, overhead can be eliminatedfor that case without sacrificing flexibility. This takes fulladvantage of any ability of the optimizer to crush out degeneratecode.The library specifies many virtual functions which current linkersload even when they cannot be called. Some minor improvements to thecompiler and to ld would eliminate any such overhead by simplyomitting virtual functions that the complete program does not call.A prototype of this work has already been done. For targets whereGNU ld is not used, a "pre-linker" could do the same job.The main areas in the standard interface where user flexibilitycan result in overhead are:- Allocators: Containers are specified to use user-definableallocator types and objects, making tuning for the containercharacteristics tricky.- Locales: the standard specifies locale objects used to implementiostream operations, involving many virtual functions which usestreambuf 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 theirown types, and specify the operations the stream must use on thesetypes.Note that these sources of overhead are _avoidable_. The techniquesto avoid them are covered below.Code Bloat----------In the SGI STL, and in some other headers, many of the templatesare defined "inline" -- either explicitly or by their placementin class definitions -- which should not be inline. This is asource of code bloat. Matt had remarked that he was relying onthe compiler to recognize what was too big to benefit from inlining,and generate it out-of-line automatically. However, this also canresult in code bloat except where the linker can eliminate the extracopies.Fixing these cases will require an audit of all inline functionsdefined in the library to determine which merit inlining, and movingthe rest out of line. This is an issue mainly in chapters 23, 25, and27. Of course it can be done incrementally, and we should generallyaccept patches that move large functions out of line and into ".tcc"files, which can later be pulled into a repository. Compiler/linkerimprovements to recognize very large inline functions and move themout-of-line, but shared among compilation units, could make thiswork unnecessary.Pre-instantiating template specializations currently produces largeamounts of dead code which bloats statically linked programs. Thecurrent state of the static library, libstdc++.a, is intolerable onthis account, and will fuel further confused speculation about a needfor a library "subset". A compiler improvement that treats eachinstantiated function as a separate object file, for linking purposes,would be one solution to this problem. An alternative would be tosplit up the manual instantiation files into dozens upon dozens oflittle files, each compiled separately, but an abortive attempt atthis was done for <string> and, though it is far from complete, itis already a nuisance. A better interim solution (just until we have"export") is badly needed.When building a shared library, the current compiler/linker cannotautomatically generate the instantiations needed. This creates amiserable situation; it means any time something is changed in thelibrary, before a shared library can be built someone must manuallycopy the declarations of all templates that are needed by other partsof the library to an "instantiation" file, and add it to the buildsystem to be compiled and linked to the library. This process isreadily automated, and should be automated as soon as possible.Users building their own shared libraries experience identicalfrustrations.Sharing common aspects of template definitions among instantiationscan radically reduce code bloat. The compiler could help a greatdeal here by recognizing when a function depends on nothing abouta template parameter, or only on its size, and giving the resultingfunction a link-name "equate" that allows it to be shared with otherinstantiations. Implementation code could take advantage of thecapability by factoring out code that does not depend on the templateargument into separate functions to be merged by the compiler.Until such a compiler optimization is implemented, much can be donemanually (if tediously) in this direction. One such optimization isto derive class templates from non-template classes, and move as muchimplementation as possible into the base class. Another is to partial-specialize certain common instantiations, such as vector<T*>, to sharecode for instantiations on all types T. While these techniques work,they are far from the complete solution that a compiler improvementwould afford.Overhead: Expensive Language Features-------------------------------------The main "expensive" language feature used in the standard libraryis exception support, which requires compiling in cleanup code withstatic table data to locate it, and linking in library code to usethe table. For small embedded programs the amount of such librarycode and table data is assumed by some to be excessive. Under the"new" ABI this perception is generally exaggerated, although in somecases it may actually be excessive.To implement a library which does not use exceptions directly isnot difficult given minor compiler support (to "turn off" exceptionsand ignore exception constructs), and results in no great librarymaintenance 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. Compilersupport is not strictly necessary, except in the case of "functiontry 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 thelibrary implementation, and use of macros in this way can makecorrect diagnostics impossible. Furthermore, use of this schemewould require the library to call a function to re-throw exceptionsfrom a try block. Implementing the above semantics in the compileris preferable.Given the support above (however implemented) it only remains toreplace code that "throws" with a call to a well-documented "handler"function in a separate compilation unit which may be replaced bythe user. The main source of exceptions that would be difficultfor users to avoid is memory allocation failures, but users candefine their own memory allocation primitives that never throw.Otherwise, the complete list of such handlers, and which libraryfunctions may call them, would be needed for users to be able toimplement the necessary substitutes. (Fortunately, they have thesource code.)Opportunities-------------The template capabilities of C++ offer enormous opportunities foroptimizing common library operations, well beyond what would beconsidered "eliminating overhead". In particular, many operationsdone in Glibc with macros that depend on proprietary languageextensions 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 wherethe component where they would appear is discussed. Of course newopportunities will be identified during implementation.Unimplemented Required Library Features---------------------------------------The standard specifies hundreds of components, grouped broadly bychapter. These are listed in excruciating detail in the CHECKLISTfile.17 general18 support19 diagnostics20 utilities21 string22 locale23 containers24 iterators25 algorithms26 numerics27 iostreamsAnnex D backward compatibilityAnyone participating in implementation of the library should obtaina copy of the standard, ISO 14882. People in the U.S. can obtain anelectronic copy for US$18 from ANSI's web site. Those from othercountries should visit http://www.iso.ch/ to find out the locationof their country's representation in ISO, in order to know who cansell them a copy.The emphasis in the following sections is on unimplemented featuresand optimization opportunities.Chapter 17 General-------------------Chapter 17 concerns overall library requirements.The standard doesn't mention threads. A multi-thread (MT) extensionprimarily affects operators new and delete (18), allocator (20),string (21), locale (22), and iostreams (27). The common underlyingsupport needed for this is discussed under chapter 20.The standard requirements on names from the C headers create alot of work, mostly done. Names in the C headers must be visiblein the std:: and sometimes the global namespace; the names in thetwo scopes must refer to the same object. More stringent is thatKoenig lookup implies that any types specified as defined in std::really are defined in std::. Names optionally implemented asmacros in C cannot be macros in C++. (An overview may be read at<http://www.cantrip.org/cheaders.html>). The scripts "inclosure"and "mkcshadow", and the directories shadow/ and cshadow/, are thebeginning of an effort to conform in this area.A correct conforming definition of C header names based on underlyingC library headers, and practical linking of conforming namespacedcustomer code with third-party C libraries depends ultimately onan ABI change, allowing namespaced C type names to be mangled intotype names as if they were global, somewhat as C function names in anamespace, or C++ global variable names, are left unmangled. Perhapsanother "extern" mode, such as 'extern "C-global"' would be anappropriate place for such type definitions. Such a type wouldaffect mangling as follows:namespace A {struct X {};extern "C-global" { // or maybe just 'extern "C"'struct Y {};};}void f(A::X*); // mangles to f__FPQ21A1Xvoid 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 benecessary.) This would allow functions declared in non-standard C headers(and thus fixable by neither us nor users) to link properly with functionsdeclared using C types defined in properly-namespaced headers. Theproblem this solves is that C headers (which C++ programmers do persistin using) frequently forward-declare C struct tags without includingthe header where the type is defined, as instruct tm;void munge(tm*);Without some compiler accommodation, munge cannot be called by correctC++ 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 seemsalso to wrap the whole header in an 'extern "C"' block, so it'sunusable for C++ headers. The correct solution appears to be toallow the various special include-directory options, if not givenan 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/extthe compiler would search $(prefix)/g++-v3 and not reportpedantic warnings for files found there, but treat files in$(prefix)/g++-v3/ext pedantically. (The undocumented semanticsof "-isystem" in g++ stink. Can they be rescinded? If not itmust be replaced with something more rationally behaved.)All the C headers need the treatment above; in the standard theseheaders are mentioned in various chapters. Below, I have onlymentioned those that present interesting implementation issues.The components identified as "mostly complete", below, have not beenaudited for conformance. In many cases where the library passesconformance tests we have non-conforming extensions that must bewrapped in #if guards for "pedantic" use, and in some cases renamedin a conforming way for continued use in the implementation regardlessof conformance flags.The STL portion of the library still depends on a headerstl/bits/stl_config.h full of #ifdef clauses. This apparatusshould be replaced with autoconf/automake machinery.The SGI STL defines a type_traits<> template, specialized formany types in their code including the built-in numeric andpointer types and some library types, to direct optimizations ofstandard functions. The SGI compiler has been extended to generatespecializations of this template automatically for user types,so that use of STL templates on user types can take advantage ofthese optimizations. Specializations for other, non-STL, typeswould make more optimizations possible, but extending the gcccompiler in the same way would be much better. Probably the nextround of standardization will ratify this, but probably withchanges, so it probably should be renamed to place it in theimplementation namespace.The SGI STL also defines a large number of extensions visible instandard headers. (Other extensions that appear in separate headershave been sequestered in subdirectories ext/ and backward/.) Allthese extensions should be moved to other headers where possible,and in any case wrapped in a namespace (not std!), and (where keptin a standard header) girded about with macro guards. Some cannot bemoved out of standard headers because they are used to implementstandard features. The canonical method for accommodating theseis to use a protected name, aliased in macro guards to a user-spacename. Unfortunately C++ offers no satisfactory template typedefmechanism, so very ad-hoc and unsatisfactory aliasing must be usedinstead.Implementation of a template typedef mechanism should have the highestpriority among possible extensions, on the same level as implementationof the template "export" feature.Chapter 18 Language support----------------------------Headers: <limits> <new> <typeinfo> <exception>C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp><ctime> <csignal> <cstdlib> (also 21, 25, 26)This defines the built-in exceptions, rtti, numeric_limits<>,operator new and delete. Much of this is provided by thecompiler in its static runtime library.Work to do includes defining numeric_limits<> specializations inseparate files for all target architectures. Values for integer typesexcept for bool and wchar_t are readily obtained from the C header<limits.h>, but values for the remaining numeric types (bool, wchar_t,float, double, long double) must be entered manually. This islargely dog work except for those members whose values are noteasily deduced from available documentation. Also, this involvessome work in target configuration to identify the correct choice offile to build against and to install.The definitions of the various operators new and delete must bemade thread-safe, which depends on a portable exclusion mechanism,discussed under chapter 20. Of course there is always plenty ofroom for improvements to the speed of operators new and delete.<cstdarg>, in Glibc, defines some macros that gcc does not allow tobe wrapped into an inline function. Probably this header will demandattention whenever a new target is chosen. The functions atexit(),exit(), and abort() in cstdlib have different semantics in C++, somust be re-implemented for C++.Chapter 19 Diagnostics-----------------------Headers: <stdexcept>C headers: <cassert> <cerrno>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 ina function call.Chapter 20 Utilities---------------------Headers: <utility> <functional> <memory>C header: <ctime> (also in 18)SGI STL provides "mostly complete" versions of all the componentsdefined in this chapter. However, the auto_ptr<> implementationis known to be wrong. Furthermore, the standard definition of itis known to be unimplementable as written. A minor change to thestandard would fix it, and auto_ptr<> should be adjusted to match.Multi-threading affects the allocator implementation, and there mustbe configuration/installation choices for different users' MTrequirements. Anyway, users will want to tune allocator optionsto support different target conditions, MT or no.The primitives used for MT implementation should be exposed, as anextension, 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 configurableto be stubbed out for non-MT use, or to use an appropriately-loadeddynamic library for the actual runtime environment, or staticallycompiled in for cases where the target architecture is known.Chapter 21 String------------------Headers: <string>C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27)<cstdlib> (also in 18, 25, 26)We have "mostly-complete" char_traits<> implementations. Many of thechar_traits<char> operations might be optimized further using existingproprietary language extensions.We have a "mostly-complete" basic_string<> implementation. The workto manually instantiate char and wchar_t specializations in objectfiles to improve link-time behavior is extremely unsatisfactory,literally tripling library-build time with no commensurate improvementin static program link sizes. It must be redone. (Similar work isneeded for some components in chapters 22 and 27.)Other work needed for strings is MT-safety, as discussed under thechapter 20 heading.The standard C type mbstate_t from <cwchar> and used in char_traits<>must be different in C++ than in C, because in C++ the default constructorvalue 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 touse 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 accommodatingthan what might be provided by an underlying C library.There remain some basic_string template-member functions which donot overload properly with their non-template brethren. The infamoushack akin to what was done in vector<> is needed, to conform to23.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 characterpointers, with class objects would greatly increase the safety of theclient interface, and also permit a "debug" mode in which range,ownership, and validity are rigorously checked. The current use ofraw pointers as string iterators is evil. vector<> iterators need thesame treatment. Note that the current implementation freely mixespointers and iterators, and that must be fixed before safer iteratorscan be introduced.Some of the functions in <cstring> are different from the C version.generally overloaded on const and non-const argument pointers. Forexample, in <cstring> strchr is overloaded. The functions isupperetc. in <cctype> typically implemented as macros in C are functionsin C++, because they are overloaded with others of the same namedefined in <locale>.Many of the functions required in <cwctype> and <cwchar> cannot beimplemented using underlying C facilities on intended targets becausesuch facilities only partly exist.Chapter 22 Locale------------------Headers: <locale>C headers: <clocale>We have a "mostly complete" class locale, with the exception ofcode 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 targetenvironments. This code must be written in various versions andchosen by configuration parameters.Members of many of the facets defined in <locale> are stubs. Generally,there are two sets of facets: the base class facets (which are supposedto implement the "C" locale) and the "byname" facets, which are supposedto read files to determine their behavior. The base ctype<>, collate<>,and numpunct<> facets are "mostly complete", except that the table ofbitmask values used for "is" operations, and corresponding mask values,are still defined in libio and just included/linked. (We will need toimplement these tables independently, soon, but should take advantageof libio where possible.) The num_put<>::put members for integer typesare "mostly complete".A complete list of what has and has not been implemented may befound in CHECKLIST. However, note that the current definition ofcodecvt<wchar_t,char,mbstate_t> is wrong. It should simply writeout the raw bytes representing the wide characters, rather thantrying 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<> facetsare used by other library facilities defined in <string>, <istream>,and <ostream>, and the codecvt<> facet is used by basic_filebuf<>in <fstream>, so a conforming iostream implementation depends onthese.The "long long" type eventually must be supported, but code mentioningit should be wrapped in #if guards to allow pedantic-mode compiling.Performance of num_put<> and num_get<> depend critically oncaching computed values in ios_base objects, and on extensionsto the interface with streambufs.Specifically: retrieving a copy of the locale object, extractingthe needed facets, and gathering data from them, for each call to(e.g.) operator<< would be prohibitively slow. To cache formatdata for use by num_put<> and num_get<> we have a _Format_cache<>object stored in the ios_base::pword() array. This is constructedand initialized lazily, and is organized purely for utility. Itis discarded when a new locale with different facets is imbued.Using only the public interfaces of the iterator arguments to thefacet functions would limit performance by forbidding "vector-style"character operations. The streambuf iterator optimizations aredescribed under chapter 24, but facets can also bypass the streambufiterators via explicit specializations and operate directly on thestreambufs, and use extended interfaces to get direct access to thestreambuf internal buffer arrays. These extensions are mentionedunder chapter 27. These optimizations are particularly importantfor input parsing.Unused virtual members of locale facets can be omitted, as mentionedabove, by a smart linker.Chapter 23 Containers----------------------Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset>All the components in chapter 23 are implemented in the SGI STL.They are "mostly complete"; they include a large number ofnonconforming extensions which must be wrapped. Some of theseare used internally and must be renamed or duplicated.The SGI components are optimized for large-memory environments. Forembedded targets, different criteria might be more appropriate. Userswill want to be able to tune this behavior. We should provideways for users to compile the library with different memory usagecharacteristics.A lot more work is needed on factoring out common code from differentspecializations to reduce code size here and in chapter 25. Theeasiest fix for this would be a compiler/ABI improvement that allowsthe compiler to recognize when a specialization depends only on thesize (or other gross quality) of a template argument, and allow thelinker to share the code with similar specializations. In itsabsence, many of the algorithms and containers can be partial-specialized, at least for the case of pointers, but this only solvesa small part of the problem. Use of a type_traits-style templateallows a few more optimization opportunities, more if the compilercan generate the specializations automatically.As an optimization, containers can specialize on the default allocatorand bypass it, or take advantage of details of its implementationafter it has been improved upon.Replacing the vector iterators, which currently are simple elementpointers, with class objects would greatly increase the safety of theclient interface, and also permit a "debug" mode in which range,ownership, and validity are rigorously checked. The current use ofpointers for iterators is evil.As mentioned for chapter 24, the deque iterator is a good example ofan opportunity to implement a "staged" iterator that would benefitfrom specializations of some algorithms.Chapter 24 Iterators---------------------Headers: <iterator>Standard iterators are "mostly complete", with the exception ofthe stream iterators, which are not yet templatized on thestream type. Also, the base class template iterator<> appearsto 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 offriendship with the streambuf implementation.Matt Austern has identified opportunities where certain iteratortypes, particularly including streambuf iterators and dequeiterators, have a "two-stage" quality, such that an intermediatelimit can be checked much more quickly than the true limit onrange operations. If identified with a member of iterator_traits,algorithms may be specialized for this case. Of course theiterators that have this quality can be identified by specializinga traits class.Many of the algorithms must be specialized for the streambufiterators, to take advantage of block-mode operations, in orderto allow iostream/locale operations' performance not to suffer.It may be that they could be treated as staged iterators andtake advantage of those optimizations.Chapter 25 Algorithms----------------------Headers: <algorithm>C headers: <cstdlib> (also in 18, 21, 26))The algorithms are "mostly complete". As mentioned above, theyare optimized for speed at the expense of code and data size.Specializations of many of the algorithms for non-STL types wouldgive performance improvements, but we must use great care not tointerfere with fragile template overloading semantics for thestandard interfaces. Conventionally the standard function templateinterface is an inline which delegates to a non-standard functionwhich is then overloaded (this is already done in many places inthe library). Particularly appealing opportunities for the sake ofiostream performance are for copy and find applied to streambufiterators or (as noted elsewhere) for staged iterators, of whichthe streambuf iterators are a good example.The bsearch and qsort functions cannot be overloaded properly asrequired by the standard because gcc does not yet allow overloadingon the extern-"C"-ness of a function pointer.Chapter 26 Numerics--------------------Headers: <complex> <valarray> <numeric>C headers: <cmath>, <cstdlib> (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 courseoptimization opportunities abound for the numerically literate. Itis not clear whether the valarray implementation really conformsfully, in the assumptions it makes about aliasing (and lack thereof)in its arguments.The C div() and ldiv() functions are interesting, because they are theonly 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() andldiv() cannot be re-used efficiently. Fortunately they are trivial tore-implement.Chapter 27 Iostreams---------------------Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream><iomanip> <sstream> <fstream>C headers: <cstdio> <cwchar> (also in 21)Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>,ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> andbasic_ostream<> are well along, but basic_istream<> has had little workdone. The standard stream objects, <sstream> and <fstream> have beenstarted; basic_filebuf<> "write" functions have been implemented justenough to do "hello, world".Most of the istream and ostream operators << and >> (with the exceptionof 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 andwchar_t in a way that links only used members into user programs.Streambuf is fertile ground for optimization extensions. An extendedinterface giving iterator access to its internal buffer would be veryuseful for other library components.Iostream operations (primarily operators << and >>) can take advantageof the case where user code has not specified a locale, and bypass localeoperations entirely. The current implementation of op<</num_put<>::put,for the integer types, demonstrates how they can cache encoding detailsfrom the locale on each operation. There is lots more room foroptimization in this area.The definition of the relationship between the standard streamscout et al. and stdout et al. requires something like a "stdiobuf".The SGI solution of using double-indirection to actually use astdio FILE object for buffering is unsatisfactory, because itinterferes with peephole loop optimizations.The <sstream> header work has begun. stringbuf can benefit fromfriendship with basic_string<> and basic_string<>::_Rep to usethose objects directly as buffers, and avoid allocating and makingcopies.The basic_filebuf<> template is a complex beast. It is specified touse the locale facet codecvt<> to translate characters between nativefiles and the locale character encoding. In general this involvestwo buffers, one of "char" representing the file and another of"char_type", for the stream, with codecvt<> translating. The processis complicated by the variable-length nature of the translation, andthe need to seek to corresponding places in the two representations.For the case of basic_filebuf<char>, when no translation is needed,a single buffer suffices. A specialized filebuf can be used to reducecode space overhead when no locale has been imbued. Matt Austern'swork at SGI will be useful, perhaps directly as a source of code, orat least as an example to draw on.Filebuf, almost uniquely (cf. operator new), depends heavily onunderlying environmental facilities. In current releases iostreamdepends fairly heavily on libio constant definitions, but it shouldbe made independent. It also depends on operating system primitivesfor file operations. There is immense room for optimizations using(e.g.) mmap for reading. The shadow/ directory wraps, besides thestandard C headers, the libio.h and unistd.h headers, for use mainlyby filebuf. These wrappings have not been completed, though thereis scaffolding in place.The encapsulation of certain C header <cstdio> names presents aninteresting problem. It is possible to define an inline std::fprintf()implemented in terms of the 'extern "C"' vfprintf(), but there is nostandard vfscanf() to use to implement std::fscanf(). It appears thatvfscanf but be re-implemented in C++ for targets where no vfscanfextension has been defined. This is interesting in that it seemsto be the only significant case in the C library where this kind ofrewriting is necessary. (Of course Glibc provides the vfscanf()extension.) (The functions related to exit() must be rewrittenfor other reasons.)Annex D-------Headers: <strstream>Annex D defines many non-library features, and many minormodifications to various headers, and a complete header.It is "mostly done", except that the libstdc++-2 <strstream>header has not been adopted into the library, or checked toverify that it matches the draft in those details that wereclarified by the committee. Certainly it must at least bemoved into the std namespace.We still need to wrap all the deprecated features in #if guardsso that pedantic compile modes can detect their use.Nonstandard Extensions----------------------Headers: <iostream.h> <strstream.h> <hash> <rbtree><pthread_alloc> <stdiobuf> (etc.)User code has come to depend on a variety of nonstandard componentsthat we must not omit. Much of this code can be adopted fromlibstdc++-v2 or from the SGI STL. This particularly includes<iostream.h>, <strstream.h>, and various SGI extensions suchas <hash_map.h>. Many of these are already placed in thesubdirectories ext/ and backward/. (Note that it is better toinclude them via "<backward/hash_map.h>" or "<ext/hash_map>" thanto search the subdirectory itself via a "-I" directive.</literallayout></sect1></appendix>