xref: /netbsd-src/external/gpl3/gcc/dist/libstdc++-v3/doc/xml/manual/appendix_contributing.xml (revision 0a3071956a3a9fdebdbf7f338cf2d439b45fc728)
148fb7bfaSmrg<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
248fb7bfaSmrg	  xml:id="appendix.contrib" xreflabel="Contributing">
34fee23f9Smrg<?dbhtml filename="appendix_contributing.html"?>
44fee23f9Smrg
548fb7bfaSmrg<info><title>
64fee23f9Smrg  Contributing
74fee23f9Smrg  <indexterm>
84fee23f9Smrg    <primary>Appendix</primary>
94fee23f9Smrg    <secondary>Contributing</secondary>
104fee23f9Smrg  </indexterm>
114fee23f9Smrg</title>
1248fb7bfaSmrg  <keywordset>
1348fb7bfaSmrg    <keyword>ISO C++</keyword>
1448fb7bfaSmrg    <keyword>library</keyword>
1548fb7bfaSmrg  </keywordset>
1648fb7bfaSmrg</info>
1748fb7bfaSmrg
1848fb7bfaSmrg
194fee23f9Smrg
204fee23f9Smrg<para>
214d5abbe8Smrg  The GNU C++ Library is part of GCC and follows the same development model,
224d5abbe8Smrg  so the general rules for
23*0a307195Smrg  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/contribute.html">contributing
244d5abbe8Smrg  to GCC</link> apply. Active
254d5abbe8Smrg  contributors are assigned maintainership responsibility, and given
264d5abbe8Smrg  write access to the source repository. First-time contributors
274fee23f9Smrg  should follow this procedure:
284fee23f9Smrg</para>
294fee23f9Smrg
3048fb7bfaSmrg<section xml:id="contrib.list" xreflabel="Contributor Checklist"><info><title>Contributor Checklist</title></info>
314fee23f9Smrg
3248fb7bfaSmrg
3348fb7bfaSmrg  <section xml:id="list.reading"><info><title>Reading</title></info>
3448fb7bfaSmrg
354fee23f9Smrg
364fee23f9Smrg    <itemizedlist>
374fee23f9Smrg      <listitem>
384fee23f9Smrg	<para>
394fee23f9Smrg	  Get and read the relevant sections of the C++ language
404fee23f9Smrg	  specification. Copies of the full ISO 14882 standard are
414fee23f9Smrg	  available on line via the ISO mirror site for committee
424fee23f9Smrg	  members. Non-members, or those who have not paid for the
434fee23f9Smrg	  privilege of sitting on the committee and sustained their
444fee23f9Smrg	  two meeting commitment for voting rights, may get a copy of
454fee23f9Smrg	  the standard from their respective national standards
464fee23f9Smrg	  organization. In the USA, this national standards
4748fb7bfaSmrg	  organization is
48b17d1066Smrg	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ansi.org">ANSI</link>.
49b17d1066Smrg	  (And if you've already registered with them you can <link
50b17d1066Smrg	  xmlns:xlink="http://www.w3.org/1999/xlink"
51fb8a8121Smrg	  xlink:href="https://webstore.ansi.org/Standards/ISO/ISOIEC148822014">buy
52b17d1066Smrg	  the standard on-line</link>.)
534fee23f9Smrg	</para>
544fee23f9Smrg      </listitem>
554fee23f9Smrg
564fee23f9Smrg      <listitem>
574fee23f9Smrg	<para>
584fee23f9Smrg	  The library working group bugs, and known defects, can
594fee23f9Smrg	  be obtained here:
6048fb7bfaSmrg	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21</link>
614fee23f9Smrg	</para>
624fee23f9Smrg      </listitem>
634fee23f9Smrg
644fee23f9Smrg      <listitem>
654fee23f9Smrg	<para>
664fee23f9Smrg	  Peruse
67*0a307195Smrg	  the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/prep/standards/">GNU
6848fb7bfaSmrg	  Coding Standards</link>, and chuckle when you hit the part
694fee23f9Smrg	  about <quote>Using Languages Other Than C</quote>.
704fee23f9Smrg	</para>
714fee23f9Smrg      </listitem>
724fee23f9Smrg
734fee23f9Smrg      <listitem>
744fee23f9Smrg	<para>
754fee23f9Smrg	  Be familiar with the extensions that preceded these
764fee23f9Smrg	  general GNU rules. These style issues for libstdc++ can be
7748fb7bfaSmrg	  found in <link linkend="contrib.coding_style">Coding Style</link>.
784fee23f9Smrg      </para>
794fee23f9Smrg      </listitem>
804fee23f9Smrg
814fee23f9Smrg      <listitem>
824fee23f9Smrg	<para>
834fee23f9Smrg	  And last but certainly not least, read the
8448fb7bfaSmrg	  library-specific information found in
8548fb7bfaSmrg          <link linkend="appendix.porting">Porting and Maintenance</link>.
864fee23f9Smrg      </para>
874fee23f9Smrg      </listitem>
884fee23f9Smrg    </itemizedlist>
894fee23f9Smrg
9048fb7bfaSmrg  </section>
9148fb7bfaSmrg  <section xml:id="list.copyright"><info><title>Assignment</title></info>
9248fb7bfaSmrg
934fee23f9Smrg    <para>
94*0a307195Smrg      See the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/contribute.html#legal">legal prerequisites</link> for all GCC contributions.
954fee23f9Smrg    </para>
964fee23f9Smrg
974fee23f9Smrg    <para>
984fee23f9Smrg      Historically, the libstdc++ assignment form added the following
994fee23f9Smrg      question:
1004fee23f9Smrg    </para>
1014fee23f9Smrg
1024fee23f9Smrg    <para>
1034fee23f9Smrg      <quote>
1044fee23f9Smrg	Which Belgian comic book character is better, Tintin or Asterix, and
1054fee23f9Smrg	why?
1064fee23f9Smrg      </quote>
1074fee23f9Smrg    </para>
1084fee23f9Smrg
1094fee23f9Smrg    <para>
1104fee23f9Smrg      While not strictly necessary, humoring the maintainers and answering
1114fee23f9Smrg      this question would be appreciated.
1124fee23f9Smrg    </para>
1134fee23f9Smrg
1144fee23f9Smrg    <para>
1154d5abbe8Smrg      Please contact
1164d5abbe8Smrg      Paolo Carlini at <email>paolo.carlini@oracle.com</email>
1174d5abbe8Smrg      or
1184d5abbe8Smrg      Jonathan Wakely at <email>jwakely+assign@redhat.com</email>
1194d5abbe8Smrg      if you are confused about the assignment or have general licensing
1204d5abbe8Smrg      questions. When requesting an assignment form from
1214d5abbe8Smrg      <email>assign@gnu.org</email>, please CC the libstdc++
1224d5abbe8Smrg      maintainers above so that progress can be monitored.
1234fee23f9Smrg    </para>
12448fb7bfaSmrg  </section>
1254fee23f9Smrg
12648fb7bfaSmrg  <section xml:id="list.getting"><info><title>Getting Sources</title></info>
12748fb7bfaSmrg
1284fee23f9Smrg    <para>
129fb8a8121Smrg      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/gitwrite.html">Getting write access
13048fb7bfaSmrg	(look for "Write after approval")</link>
1314fee23f9Smrg    </para>
13248fb7bfaSmrg  </section>
1334fee23f9Smrg
13448fb7bfaSmrg  <section xml:id="list.patches"><info><title>Submitting Patches</title></info>
13548fb7bfaSmrg
1364fee23f9Smrg
1374fee23f9Smrg    <para>
1384fee23f9Smrg      Every patch must have several pieces of information before it can be
1394fee23f9Smrg      properly evaluated. Ideally (and to ensure the fastest possible
1404fee23f9Smrg      response from the maintainers) it would have all of these pieces:
1414fee23f9Smrg    </para>
1424fee23f9Smrg
1434fee23f9Smrg    <itemizedlist>
1444fee23f9Smrg      <listitem>
1454fee23f9Smrg	<para>
1464fee23f9Smrg	  A description of the bug and how your patch fixes this
1474fee23f9Smrg	  bug. For new features a description of the feature and your
1484fee23f9Smrg	  implementation.
1494fee23f9Smrg	</para>
1504fee23f9Smrg      </listitem>
1514fee23f9Smrg
1524fee23f9Smrg      <listitem>
1534fee23f9Smrg	<para>
154*0a307195Smrg	  A ChangeLog entry as part of the Git commit message. Check
155*0a307195Smrg	  some recent commits for format and content. The
156*0a307195Smrg	  <filename>contrib/mklog.py</filename> script can be used to
157*0a307195Smrg	  generate a ChangeLog template for commit messages. See
158*0a307195Smrg	  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/gitwrite.html">Read-write Git access</link>
159*0a307195Smrg	  for scripts and aliases that are useful here.
1604fee23f9Smrg	</para>
1614fee23f9Smrg      </listitem>
1624fee23f9Smrg
1634fee23f9Smrg      <listitem>
1644fee23f9Smrg	<para>
1654fee23f9Smrg	  A testsuite submission or sample program that will
1664fee23f9Smrg	  easily and simply show the existing error or test new
1674fee23f9Smrg	  functionality.
1684fee23f9Smrg	</para>
1694fee23f9Smrg      </listitem>
1704fee23f9Smrg
1714fee23f9Smrg      <listitem>
1724fee23f9Smrg	<para>
173a3e9eb18Smrg	  The patch itself. If you are using the Git repository use
174*0a307195Smrg	  <command>git show</command> or <command>git format-patch</command>
175a3e9eb18Smrg	  to produce a patch;
176a3e9eb18Smrg	  otherwise, use <command>diff -cp OLD NEW</command>. If your
1774fee23f9Smrg	  version of diff does not support these options, then get the
178a3e9eb18Smrg	  latest version of GNU diff.
1794fee23f9Smrg	</para>
1804fee23f9Smrg      </listitem>
1814fee23f9Smrg
1824fee23f9Smrg      <listitem>
1834fee23f9Smrg	<para>
1844fee23f9Smrg	  When you have all these pieces, bundle them up in a
1854fee23f9Smrg	  mail message and send it to libstdc++@gcc.gnu.org. All
1864fee23f9Smrg	  patches and related discussion should be sent to the
187f9a78e0eSmrg	  libstdc++ mailing list. In common with the rest of GCC,
188f9a78e0eSmrg	  patches should also be sent to the gcc-patches mailing list.
189*0a307195Smrg	  So you could send your email To:libstdc++@gcc.gnu.org and
190*0a307195Smrg	  Cc:gcc-patches@gcc.gnu.org for example.
1914fee23f9Smrg	</para>
1924fee23f9Smrg      </listitem>
1934fee23f9Smrg    </itemizedlist>
1944fee23f9Smrg
19548fb7bfaSmrg  </section>
1964fee23f9Smrg
19748fb7bfaSmrg</section>
1984fee23f9Smrg
19948fb7bfaSmrg<section xml:id="contrib.organization" xreflabel="Source Organization"><info><title>Directory Layout and Source Conventions</title></info>
2004fee23f9Smrg  <?dbhtml filename="source_organization.html"?>
20148fb7bfaSmrg
2024fee23f9Smrg
2034fee23f9Smrg  <para>
2043f4ceed9Smrg    The <filename class="directory">libstdc++-v3</filename> directory in the
2053f4ceed9Smrg    GCC sources contains the files needed to create the GNU C++ Library.
2064fee23f9Smrg  </para>
2074fee23f9Smrg
2083f4ceed9Smrg<para>
2094fee23f9SmrgIt has subdirectories:
2103f4ceed9Smrg</para>
2114fee23f9Smrg
2123f4ceed9Smrg<variablelist>
2133f4ceed9Smrg  <varlistentry>
2143f4ceed9Smrg  <term><filename class="directory">doc</filename></term>
2153f4ceed9Smrg  <listitem>
2164fee23f9Smrg    Files in HTML and text format that document usage, quirks of the
2174fee23f9Smrg    implementation, and contributor checklists.
2183f4ceed9Smrg    </listitem>
2193f4ceed9Smrg  </varlistentry>
2204fee23f9Smrg
2213f4ceed9Smrg  <varlistentry>
2223f4ceed9Smrg  <term><filename class="directory">include</filename></term>
2233f4ceed9Smrg  <listitem>
2244fee23f9Smrg    All header files for the C++ library are within this directory,
2254fee23f9Smrg    modulo specific runtime-related files that are in the libsupc++
2264fee23f9Smrg    directory.
2274fee23f9Smrg
2283f4ceed9Smrg    <variablelist>
2293f4ceed9Smrg    <varlistentry>
2303f4ceed9Smrg    <term><filename class="directory">include/std</filename></term>
2313f4ceed9Smrg    <listitem>
2323f4ceed9Smrg      Files meant to be found by <code>#include &lt;name&gt;</code> directives
2333f4ceed9Smrg      in standard-conforming user programs.
2343f4ceed9Smrg      </listitem>
2353f4ceed9Smrg    </varlistentry>
2364fee23f9Smrg
2373f4ceed9Smrg    <varlistentry>
2383f4ceed9Smrg    <term><filename class="directory">include/c</filename></term>
2393f4ceed9Smrg    <listitem>
2404fee23f9Smrg      Headers intended to directly include standard C headers.
2413f4ceed9Smrg      [NB: this can be enabled via <option>--enable-cheaders=c</option>]
2423f4ceed9Smrg      </listitem>
2433f4ceed9Smrg    </varlistentry>
2444fee23f9Smrg
2453f4ceed9Smrg    <varlistentry>
2463f4ceed9Smrg    <term><filename class="directory">include/c_global</filename></term>
2473f4ceed9Smrg    <listitem>
2484fee23f9Smrg      Headers intended to include standard C headers in
2493f4ceed9Smrg      the global namespace, and put select names into the <code>std::</code>
2504fee23f9Smrg      namespace.  [NB: this is the default, and is the same as
2513f4ceed9Smrg      <option>--enable-cheaders=c_global</option>]
2523f4ceed9Smrg      </listitem>
2533f4ceed9Smrg    </varlistentry>
2544fee23f9Smrg
2553f4ceed9Smrg    <varlistentry>
2563f4ceed9Smrg    <term><filename class="directory">include/c_std</filename></term>
2573f4ceed9Smrg    <listitem>
2584fee23f9Smrg      Headers intended to include standard C headers
2593f4ceed9Smrg      already in namespace std, and put select names into the <code>std::</code>
2603f4ceed9Smrg      namespace.  [NB: this is the same as
2613f4ceed9Smrg      <option>--enable-cheaders=c_std</option>]
2623f4ceed9Smrg      </listitem>
2633f4ceed9Smrg    </varlistentry>
2644fee23f9Smrg
2653f4ceed9Smrg    <varlistentry>
2663f4ceed9Smrg    <term><filename class="directory">include/bits</filename></term>
2673f4ceed9Smrg    <listitem>
2684fee23f9Smrg      Files included by standard headers and by other files in
2694fee23f9Smrg      the bits directory.
2703f4ceed9Smrg      </listitem>
2713f4ceed9Smrg    </varlistentry>
2724fee23f9Smrg
2733f4ceed9Smrg    <varlistentry>
2743f4ceed9Smrg    <term><filename class="directory">include/backward</filename></term>
2753f4ceed9Smrg    <listitem>
2763f4ceed9Smrg      Headers provided for backward compatibility, such as
2773f4ceed9Smrg      <filename class="headerfile">&lt;backward/hash_map&gt;</filename>.
2784fee23f9Smrg      They are not used in this library.
2793f4ceed9Smrg    </listitem>
2803f4ceed9Smrg    </varlistentry>
2814fee23f9Smrg
2823f4ceed9Smrg    <varlistentry>
2833f4ceed9Smrg    <term><filename class="directory">include/ext</filename></term>
2843f4ceed9Smrg    <listitem>
2854fee23f9Smrg      Headers that define extensions to the standard library.  No
2863f4ceed9Smrg      standard header refers to any of them, in theory (there are some
2873f4ceed9Smrg      exceptions).
2883f4ceed9Smrg    </listitem>
2893f4ceed9Smrg    </varlistentry>
290b17d1066Smrg
291b17d1066Smrg    <varlistentry>
292b17d1066Smrg    <term>
293b17d1066Smrg      <filename class="directory">include/debug</filename>,
294b17d1066Smrg      <filename class="directory">include/parallel</filename>, and
295b17d1066Smrg    </term>
296b17d1066Smrg    <listitem>
297fb8a8121Smrg      Headers that implement the Debug Mode and Parallel Mode extensions.
298b17d1066Smrg    </listitem>
299b17d1066Smrg    </varlistentry>
3003f4ceed9Smrg    </variablelist>
3013f4ceed9Smrg  </listitem>
3023f4ceed9Smrg  </varlistentry>
3034fee23f9Smrg
3043f4ceed9Smrg  <varlistentry>
3053f4ceed9Smrg  <term><filename class="directory">scripts</filename></term>
3063f4ceed9Smrg  <listitem>
3074fee23f9Smrg    Scripts that are used during the configure, build, make, or test
3084fee23f9Smrg    process.
3093f4ceed9Smrg    </listitem>
3103f4ceed9Smrg  </varlistentry>
3114fee23f9Smrg
3123f4ceed9Smrg  <varlistentry>
3133f4ceed9Smrg  <term><filename class="directory">src</filename></term>
3143f4ceed9Smrg  <listitem>
3154fee23f9Smrg    Files that are used in constructing the library, but are not
3164fee23f9Smrg    installed.
3174fee23f9Smrg
3183f4ceed9Smrg    <variablelist>
3193f4ceed9Smrg    <varlistentry>
3203f4ceed9Smrg    <term><filename class="directory">src/c++98</filename></term>
3213f4ceed9Smrg    <listitem>
3223f4ceed9Smrg    Source files compiled using <option>-std=gnu++98</option>.
3233f4ceed9Smrg      </listitem>
3243f4ceed9Smrg    </varlistentry>
3253f4ceed9Smrg
3263f4ceed9Smrg    <varlistentry>
3273f4ceed9Smrg    <term><filename class="directory">src/c++11</filename></term>
3283f4ceed9Smrg    <listitem>
3293f4ceed9Smrg    Source files compiled using <option>-std=gnu++11</option>.
3303f4ceed9Smrg      </listitem>
3313f4ceed9Smrg    </varlistentry>
3323f4ceed9Smrg
3333f4ceed9Smrg    <varlistentry>
3343f4ceed9Smrg    <term><filename class="directory">src/filesystem</filename></term>
3353f4ceed9Smrg    <listitem>
3363f4ceed9Smrg    Source files for the Filesystem TS.
3373f4ceed9Smrg      </listitem>
3383f4ceed9Smrg    </varlistentry>
3393f4ceed9Smrg
3403f4ceed9Smrg    <varlistentry>
3413f4ceed9Smrg    <term><filename class="directory">src/shared</filename></term>
3423f4ceed9Smrg    <listitem>
3433f4ceed9Smrg    Source code included by other files under both
3443f4ceed9Smrg    <filename class="directory">src/c++98</filename> and
3453f4ceed9Smrg    <filename class="directory">src/c++11</filename>
3463f4ceed9Smrg      </listitem>
3473f4ceed9Smrg    </varlistentry>
3483f4ceed9Smrg    </variablelist>
3493f4ceed9Smrg  </listitem>
3503f4ceed9Smrg  </varlistentry>
3513f4ceed9Smrg
3523f4ceed9Smrg  <varlistentry>
3533f4ceed9Smrg  <term><filename class="directory">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</filename></term>
3543f4ceed9Smrg  <listitem>
3554fee23f9Smrg    Test programs are here, and may be used to begin to exercise the
3564fee23f9Smrg    library.  Support for "make check" and "make check-install" is
3574fee23f9Smrg    complete, and runs through all the subdirectories here when this
3584fee23f9Smrg    command is issued from the build directory.  Please note that
3593f4ceed9Smrg    "make check" requires DejaGnu 1.4 or later to be installed,
3603f4ceed9Smrg    or for extra <link linkend="test.run.permutations">permutations</link>
3613f4ceed9Smrg    DejaGnu 1.5.3 or later.
3623f4ceed9Smrg    </listitem>
3633f4ceed9Smrg  </varlistentry>
3643f4ceed9Smrg</variablelist>
3654fee23f9Smrg
3663f4ceed9Smrg<para>
3674fee23f9SmrgOther subdirectories contain variant versions of certain files
3684fee23f9Smrgthat are meant to be copied or linked by the configure script.
3694fee23f9SmrgCurrently these are:
3703f4ceed9Smrg<literallayout><filename class="directory">config/abi</filename>
3713f4ceed9Smrg<filename class="directory">config/allocator</filename>
3723f4ceed9Smrg<filename class="directory">config/cpu</filename>
3733f4ceed9Smrg<filename class="directory">config/io</filename>
3743f4ceed9Smrg<filename class="directory">config/locale</filename>
3753f4ceed9Smrg<filename class="directory">config/os</filename>
3763f4ceed9Smrg</literallayout>
3773f4ceed9Smrg</para>
3784fee23f9Smrg
3793f4ceed9Smrg<para>
3804fee23f9SmrgIn addition, a subdirectory holds the convenience library libsupc++.
3813f4ceed9Smrg</para>
3824fee23f9Smrg
3833f4ceed9Smrg<variablelist>
3843f4ceed9Smrg<varlistentry>
3853f4ceed9Smrg  <term><filename class="directory">libsupc++</filename></term>
3863f4ceed9Smrg  <listitem>
3874fee23f9Smrg    Contains the runtime library for C++, including exception
3884fee23f9Smrg    handling and memory allocation and deallocation, RTTI, terminate
3894fee23f9Smrg    handlers, etc.
3903f4ceed9Smrg  </listitem>
3913f4ceed9Smrg</varlistentry>
3923f4ceed9Smrg</variablelist>
3934fee23f9Smrg
3943f4ceed9Smrg<para>
3953f4ceed9SmrgNote that glibc also has a <filename class="directory">bits/</filename>
3963f4ceed9Smrgsubdirectory.  We need to be careful not to collide with names in its
397f9a78e0eSmrg<filename class="directory">bits/</filename> directory. For example
398f9a78e0eSmrg<filename class="headerfile">&lt;bits/std_mutex.h&gt;</filename> has to be
399f9a78e0eSmrgrenamed from <filename class="headerfile">&lt;bits/mutex.h&gt;</filename>.
4003f4ceed9SmrgAnother solution would be to rename <filename class="directory">bits</filename>
4013f4ceed9Smrgto (e.g.) <filename class="directory">cppbits</filename>.
4023f4ceed9Smrg</para>
4034fee23f9Smrg
4043f4ceed9Smrg<para>
4054fee23f9SmrgIn files throughout the system, lines marked with an "XXX" indicate
4064fee23f9Smrga bug or incompletely-implemented feature.  Lines marked "XXX MT"
4074fee23f9Smrgindicate a place that may require attention for multi-thread safety.
4083f4ceed9Smrg</para>
4094fee23f9Smrg
41048fb7bfaSmrg</section>
4114fee23f9Smrg
41248fb7bfaSmrg<section xml:id="contrib.coding_style" xreflabel="Coding Style"><info><title>Coding Style</title></info>
4134fee23f9Smrg  <?dbhtml filename="source_code_style.html"?>
41448fb7bfaSmrg
4154fee23f9Smrg  <para>
4164fee23f9Smrg  </para>
417fb8a8121Smrg
418fb8a8121Smrg  <section xml:id="coding_style.bad_identifiers"><info><title>Bad Identifiers</title></info> <!-- BADNAMES -->
41948fb7bfaSmrg
4204fee23f9Smrg    <para>
4214fee23f9Smrg      Identifiers that conflict and should be avoided.
4224fee23f9Smrg    </para>
4234fee23f9Smrg
42448fb7bfaSmrg    <literallayout class="normal">
4254fee23f9Smrg      This is the list of names <quote>reserved to the
4264fee23f9Smrg      implementation</quote> that have been claimed by certain
4274fee23f9Smrg      compilers and system headers of interest, and should not be used
4284fee23f9Smrg      in the library. It will grow, of course.  We generally are
4294fee23f9Smrg      interested in names that are not all-caps, except for those like
4304fee23f9Smrg      "_T"
4314fee23f9Smrg
4324fee23f9Smrg      For Solaris:
4334fee23f9Smrg      _B
4344fee23f9Smrg      _C
4354fee23f9Smrg      _L
4364fee23f9Smrg      _N
4374fee23f9Smrg      _P
4384fee23f9Smrg      _S
4394fee23f9Smrg      _U
4404fee23f9Smrg      _X
4414fee23f9Smrg      _E1
4424fee23f9Smrg      ..
4434fee23f9Smrg      _E24
4444fee23f9Smrg
4454fee23f9Smrg      Irix adds:
4464fee23f9Smrg      _A
4474fee23f9Smrg      _G
4484fee23f9Smrg
4494fee23f9Smrg      MS adds:
4504fee23f9Smrg      _T
451fb8a8121Smrg      __deref
4524fee23f9Smrg
4534fee23f9Smrg      BSD adds:
4544fee23f9Smrg      __used
4554fee23f9Smrg      __unused
4564fee23f9Smrg      __inline
4574fee23f9Smrg      _Complex
4584fee23f9Smrg      __istype
4594fee23f9Smrg      __maskrune
4604fee23f9Smrg      __tolower
4614fee23f9Smrg      __toupper
4624fee23f9Smrg      __wchar_t
4634fee23f9Smrg      __wint_t
4644fee23f9Smrg      _res
4654fee23f9Smrg      _res_ext
4664fee23f9Smrg      __tg_*
4674fee23f9Smrg
468fb8a8121Smrg      VxWorks adds:
469fb8a8121Smrg      _C2
4704fee23f9Smrg
4714fee23f9Smrg      For GCC:
4724fee23f9Smrg
4734fee23f9Smrg      [Note that this list is out of date. It applies to the old
4744fee23f9Smrg      name-mangling; in G++ 3.0 and higher a different name-mangling is
4754fee23f9Smrg      used. In addition, many of the bugs relating to G++ interpreting
4764fee23f9Smrg      these names as operators have been fixed.]
4774fee23f9Smrg
4784fee23f9Smrg      The full set of __* identifiers (combined from gcc/cp/lex.c and
4794fee23f9Smrg      gcc/cplus-dem.c) that are either old or new, but are definitely
4804fee23f9Smrg      recognized by the demangler, is:
4814fee23f9Smrg
4824fee23f9Smrg      __aa
4834fee23f9Smrg      __aad
4844fee23f9Smrg      __ad
4854fee23f9Smrg      __addr
4864fee23f9Smrg      __adv
4874fee23f9Smrg      __aer
4884fee23f9Smrg      __als
4894fee23f9Smrg      __alshift
4904fee23f9Smrg      __amd
4914fee23f9Smrg      __ami
4924fee23f9Smrg      __aml
4934fee23f9Smrg      __amu
4944fee23f9Smrg      __aor
4954fee23f9Smrg      __apl
4964fee23f9Smrg      __array
4974fee23f9Smrg      __ars
4984fee23f9Smrg      __arshift
4994fee23f9Smrg      __as
5004fee23f9Smrg      __bit_and
5014fee23f9Smrg      __bit_ior
5024fee23f9Smrg      __bit_not
5034fee23f9Smrg      __bit_xor
5044fee23f9Smrg      __call
5054fee23f9Smrg      __cl
5064fee23f9Smrg      __cm
5074fee23f9Smrg      __cn
5084fee23f9Smrg      __co
5094fee23f9Smrg      __component
5104fee23f9Smrg      __compound
5114fee23f9Smrg      __cond
5124fee23f9Smrg      __convert
5134fee23f9Smrg      __delete
5144fee23f9Smrg      __dl
5154fee23f9Smrg      __dv
5164fee23f9Smrg      __eq
5174fee23f9Smrg      __er
5184fee23f9Smrg      __ge
5194fee23f9Smrg      __gt
5204fee23f9Smrg      __indirect
5214fee23f9Smrg      __le
5224fee23f9Smrg      __ls
5234fee23f9Smrg      __lt
5244fee23f9Smrg      __max
5254fee23f9Smrg      __md
5264fee23f9Smrg      __method_call
5274fee23f9Smrg      __mi
5284fee23f9Smrg      __min
5294fee23f9Smrg      __minus
5304fee23f9Smrg      __ml
5314fee23f9Smrg      __mm
5324fee23f9Smrg      __mn
5334fee23f9Smrg      __mult
5344fee23f9Smrg      __mx
5354fee23f9Smrg      __ne
5364fee23f9Smrg      __negate
5374fee23f9Smrg      __new
5384fee23f9Smrg      __nop
5394fee23f9Smrg      __nt
5404fee23f9Smrg      __nw
5414fee23f9Smrg      __oo
5424fee23f9Smrg      __op
5434fee23f9Smrg      __or
5444fee23f9Smrg      __pl
5454fee23f9Smrg      __plus
5464fee23f9Smrg      __postdecrement
5474fee23f9Smrg      __postincrement
5484fee23f9Smrg      __pp
5494fee23f9Smrg      __pt
5504fee23f9Smrg      __rf
5514fee23f9Smrg      __rm
5524fee23f9Smrg      __rs
5534fee23f9Smrg      __sz
5544fee23f9Smrg      __trunc_div
5554fee23f9Smrg      __trunc_mod
5564fee23f9Smrg      __truth_andif
5574fee23f9Smrg      __truth_not
5584fee23f9Smrg      __truth_orif
5594fee23f9Smrg      __vc
5604fee23f9Smrg      __vd
5614fee23f9Smrg      __vn
5624fee23f9Smrg
5634fee23f9Smrg      SGI badnames:
5644fee23f9Smrg      __builtin_alloca
5654fee23f9Smrg      __builtin_fsqrt
5664fee23f9Smrg      __builtin_sqrt
5674fee23f9Smrg      __builtin_fabs
5684fee23f9Smrg      __builtin_dabs
5694fee23f9Smrg      __builtin_cast_f2i
5704fee23f9Smrg      __builtin_cast_i2f
5714fee23f9Smrg      __builtin_cast_d2ll
5724fee23f9Smrg      __builtin_cast_ll2d
5734fee23f9Smrg      __builtin_copy_dhi2i
5744fee23f9Smrg      __builtin_copy_i2dhi
5754fee23f9Smrg      __builtin_copy_dlo2i
5764fee23f9Smrg      __builtin_copy_i2dlo
5774fee23f9Smrg      __add_and_fetch
5784fee23f9Smrg      __sub_and_fetch
5794fee23f9Smrg      __or_and_fetch
5804fee23f9Smrg      __xor_and_fetch
5814fee23f9Smrg      __and_and_fetch
5824fee23f9Smrg      __nand_and_fetch
5834fee23f9Smrg      __mpy_and_fetch
5844fee23f9Smrg      __min_and_fetch
5854fee23f9Smrg      __max_and_fetch
5864fee23f9Smrg      __fetch_and_add
5874fee23f9Smrg      __fetch_and_sub
5884fee23f9Smrg      __fetch_and_or
5894fee23f9Smrg      __fetch_and_xor
5904fee23f9Smrg      __fetch_and_and
5914fee23f9Smrg      __fetch_and_nand
5924fee23f9Smrg      __fetch_and_mpy
5934fee23f9Smrg      __fetch_and_min
5944fee23f9Smrg      __fetch_and_max
5954fee23f9Smrg      __lock_test_and_set
5964fee23f9Smrg      __lock_release
5974fee23f9Smrg      __lock_acquire
5984fee23f9Smrg      __compare_and_swap
5994fee23f9Smrg      __synchronize
6004fee23f9Smrg      __high_multiply
6014fee23f9Smrg      __unix
6024fee23f9Smrg      __sgi
6034fee23f9Smrg      __linux__
6044fee23f9Smrg      __i386__
6054fee23f9Smrg      __i486__
6064fee23f9Smrg      __cplusplus
6074fee23f9Smrg      __embedded_cplusplus
6084fee23f9Smrg      // long double conversion members mangled as __opr
6094fee23f9Smrg      // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html
61048fb7bfaSmrg      __opr
6114fee23f9Smrg    </literallayout>
61248fb7bfaSmrg  </section>
6134fee23f9Smrg
61448fb7bfaSmrg  <section xml:id="coding_style.example"><info><title>By Example</title></info>
61548fb7bfaSmrg
61648fb7bfaSmrg    <literallayout class="normal">
6174fee23f9Smrg      This library is written to appropriate C++ coding standards. As such,
6184fee23f9Smrg      it is intended to precede the recommendations of the GNU Coding
6194fee23f9Smrg      Standard, which can be referenced in full here:
6204fee23f9Smrg
621*0a307195Smrg      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/prep/standards/standards.html#Formatting">https://www.gnu.org/prep/standards/standards.html#Formatting</link>
6224fee23f9Smrg
6234fee23f9Smrg      The rest of this is also interesting reading, but skip the "Design
6244fee23f9Smrg      Advice" part.
6254fee23f9Smrg
6264fee23f9Smrg      The GCC coding conventions are here, and are also useful:
627*0a307195Smrg      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/codingconventions.html">https://gcc.gnu.org/codingconventions.html</link>
6284fee23f9Smrg
6294fee23f9Smrg      In addition, because it doesn't seem to be stated explicitly anywhere
6304fee23f9Smrg      else, there is an 80 column source limit.
6314fee23f9Smrg
63248fb7bfaSmrg      <filename>ChangeLog</filename> entries for member functions should use the
6334fee23f9Smrg      classname::member function name syntax as follows:
6344fee23f9Smrg
63548fb7bfaSmrg<code>
6364fee23f9Smrg1999-04-15  Dennis Ritchie  &lt;dr@att.com&gt;
6374fee23f9Smrg
6384fee23f9Smrg      * src/basic_file.cc (__basic_file::open): Fix thinko in
6394fee23f9Smrg      _G_HAVE_IO_FILE_OPEN bits.
64048fb7bfaSmrg</code>
6414fee23f9Smrg
6424fee23f9Smrg      Notable areas of divergence from what may be previous local practice
6434fee23f9Smrg      (particularly for GNU C) include:
6444fee23f9Smrg
6454fee23f9Smrg      01. Pointers and references
64648fb7bfaSmrg      <code>
6474fee23f9Smrg        char* p = "flop";
6484fee23f9Smrg        char&amp; c = *p;
6494fee23f9Smrg          -NOT-
6504fee23f9Smrg        char *p = "flop";  // wrong
6514fee23f9Smrg        char &amp;c = *p;      // wrong
65248fb7bfaSmrg      </code>
6534fee23f9Smrg
6544fee23f9Smrg      Reason: In C++, definitions are mixed with executable code. Here,
65548fb7bfaSmrg      <code>p</code> is being initialized, not <code>*p</code>.  This is near-universal
6564fee23f9Smrg      practice among C++ programmers; it is normal for C hackers
6574fee23f9Smrg      to switch spontaneously as they gain experience.
6584fee23f9Smrg
6594fee23f9Smrg      02. Operator names and parentheses
66048fb7bfaSmrg      <code>
6614fee23f9Smrg        operator==(type)
6624fee23f9Smrg          -NOT-
6634fee23f9Smrg        operator == (type)  // wrong
66448fb7bfaSmrg      </code>
6654fee23f9Smrg
66648fb7bfaSmrg      Reason: The <code>==</code> is part of the function name. Separating
6674fee23f9Smrg      it makes the declaration look like an expression.
6684fee23f9Smrg
6694fee23f9Smrg      03. Function names and parentheses
67048fb7bfaSmrg      <code>
6714fee23f9Smrg        void mangle()
6724fee23f9Smrg          -NOT-
6734fee23f9Smrg        void mangle ()  // wrong
67448fb7bfaSmrg      </code>
6754fee23f9Smrg
6764fee23f9Smrg      Reason: no space before parentheses (except after a control-flow
6774fee23f9Smrg      keyword) is near-universal practice for C++. It identifies the
6784fee23f9Smrg      parentheses as the function-call operator or declarator, as
6794fee23f9Smrg      opposed to an expression or other overloaded use of parentheses.
6804fee23f9Smrg
6814fee23f9Smrg      04. Template function indentation
68248fb7bfaSmrg      <code>
6834fee23f9Smrg        template&lt;typename T&gt;
6844fee23f9Smrg          void
6854fee23f9Smrg          template_function(args)
6864fee23f9Smrg          { }
6874fee23f9Smrg          -NOT-
6884fee23f9Smrg        template&lt;class T&gt;
6894fee23f9Smrg        void template_function(args) {};
69048fb7bfaSmrg      </code>
6914fee23f9Smrg
6924fee23f9Smrg      Reason: In class definitions, without indentation whitespace is
6934fee23f9Smrg      needed both above and below the declaration to distinguish
6944fee23f9Smrg      it visually from other members. (Also, re: "typename"
69548fb7bfaSmrg      rather than "class".)  <code>T</code> often could be <code>int</code>, which is
6964fee23f9Smrg      not a class. ("class", here, is an anachronism.)
6974fee23f9Smrg
6984fee23f9Smrg      05. Template class indentation
69948fb7bfaSmrg      <code>
7004fee23f9Smrg        template&lt;typename _CharT, typename _Traits&gt;
7014fee23f9Smrg          class basic_ios : public ios_base
7024fee23f9Smrg          {
7034fee23f9Smrg          public:
7044fee23f9Smrg            // Types:
7054fee23f9Smrg          };
7064fee23f9Smrg          -NOT-
7074fee23f9Smrg        template&lt;class _CharT, class _Traits&gt;
7084fee23f9Smrg        class basic_ios : public ios_base
7094fee23f9Smrg          {
7104fee23f9Smrg          public:
7114fee23f9Smrg            // Types:
7124fee23f9Smrg          };
7134fee23f9Smrg          -NOT-
7144fee23f9Smrg        template&lt;class _CharT, class _Traits&gt;
7154fee23f9Smrg          class basic_ios : public ios_base
7164fee23f9Smrg        {
7174fee23f9Smrg          public:
7184fee23f9Smrg            // Types:
7194fee23f9Smrg        };
72048fb7bfaSmrg      </code>
7214fee23f9Smrg
7224fee23f9Smrg      06. Enumerators
72348fb7bfaSmrg      <code>
7244fee23f9Smrg        enum
7254fee23f9Smrg        {
7264fee23f9Smrg          space = _ISspace,
7274fee23f9Smrg          print = _ISprint,
7284fee23f9Smrg          cntrl = _IScntrl
7294fee23f9Smrg        };
7304fee23f9Smrg          -NOT-
7314fee23f9Smrg        enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
73248fb7bfaSmrg      </code>
7334fee23f9Smrg
7344fee23f9Smrg      07. Member initialization lists
7354fee23f9Smrg      All one line, separate from class name.
7364fee23f9Smrg
73748fb7bfaSmrg      <code>
7384fee23f9Smrg        gribble::gribble()
73948fb7bfaSmrg        : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
7404fee23f9Smrg        { }
7414fee23f9Smrg          -NOT-
74248fb7bfaSmrg        gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
7434fee23f9Smrg        { }
74448fb7bfaSmrg      </code>
7454fee23f9Smrg
7464fee23f9Smrg      08. Try/Catch blocks
74748fb7bfaSmrg      <code>
7484fee23f9Smrg        try
7494fee23f9Smrg          {
7504fee23f9Smrg            //
7514fee23f9Smrg          }
7524fee23f9Smrg        catch (...)
7534fee23f9Smrg          {
7544fee23f9Smrg            //
7554fee23f9Smrg          }
7564fee23f9Smrg          -NOT-
7574fee23f9Smrg        try {
7584fee23f9Smrg          //
7594fee23f9Smrg        } catch(...) {
7604fee23f9Smrg          //
7614fee23f9Smrg        }
76248fb7bfaSmrg      </code>
7634fee23f9Smrg
7644fee23f9Smrg      09. Member functions declarations and definitions
7654fee23f9Smrg      Keywords such as extern, static, export, explicit, inline, etc
7664fee23f9Smrg      go on the line above the function name. Thus
7674fee23f9Smrg
76848fb7bfaSmrg      <code>
7694fee23f9Smrg      virtual int
7704fee23f9Smrg      foo()
7714fee23f9Smrg      -NOT-
7724fee23f9Smrg      virtual int foo()
77348fb7bfaSmrg      </code>
7744fee23f9Smrg
7754fee23f9Smrg      Reason: GNU coding conventions dictate return types for functions
7764fee23f9Smrg      are on a separate line than the function name and parameter list
7774fee23f9Smrg      for definitions. For C++, where we have member functions that can
7784fee23f9Smrg      be either inline definitions or declarations, keeping to this
7794fee23f9Smrg      standard allows all member function names for a given class to be
7804fee23f9Smrg      aligned to the same margin, increasing readability.
7814fee23f9Smrg
7824fee23f9Smrg
7834fee23f9Smrg      10. Invocation of member functions with "this-&gt;"
78448fb7bfaSmrg      For non-uglified names, use <code>this-&gt;name</code> to call the function.
7854fee23f9Smrg
78648fb7bfaSmrg      <code>
7874fee23f9Smrg      this-&gt;sync()
7884fee23f9Smrg      -NOT-
7894fee23f9Smrg      sync()
79048fb7bfaSmrg      </code>
7914fee23f9Smrg
7924fee23f9Smrg      Reason: Koenig lookup.
7934fee23f9Smrg
7944fee23f9Smrg      11. Namespaces
79548fb7bfaSmrg      <code>
7964fee23f9Smrg      namespace std
7974fee23f9Smrg      {
7984fee23f9Smrg        blah blah blah;
7994fee23f9Smrg      } // namespace std
8004fee23f9Smrg
8014fee23f9Smrg      -NOT-
8024fee23f9Smrg
8034fee23f9Smrg      namespace std {
8044fee23f9Smrg        blah blah blah;
8054fee23f9Smrg      } // namespace std
80648fb7bfaSmrg      </code>
8074fee23f9Smrg
8084fee23f9Smrg      12. Spacing under protected and private in class declarations:
8094fee23f9Smrg      space above, none below
8104fee23f9Smrg      i.e.
8114fee23f9Smrg
81248fb7bfaSmrg      <code>
8134fee23f9Smrg      public:
8144fee23f9Smrg        int foo;
8154fee23f9Smrg
8164fee23f9Smrg      -NOT-
8174fee23f9Smrg      public:
8184fee23f9Smrg
8194fee23f9Smrg        int foo;
82048fb7bfaSmrg      </code>
8214fee23f9Smrg
8224fee23f9Smrg      13. Spacing WRT return statements.
8234fee23f9Smrg      no extra spacing before returns, no parenthesis
8244fee23f9Smrg      i.e.
8254fee23f9Smrg
82648fb7bfaSmrg      <code>
8274fee23f9Smrg      }
8284fee23f9Smrg      return __ret;
8294fee23f9Smrg
8304fee23f9Smrg      -NOT-
8314fee23f9Smrg      }
8324fee23f9Smrg
8334fee23f9Smrg      return __ret;
8344fee23f9Smrg
8354fee23f9Smrg      -NOT-
8364fee23f9Smrg
8374fee23f9Smrg      }
8384fee23f9Smrg      return (__ret);
83948fb7bfaSmrg      </code>
8404fee23f9Smrg
8414fee23f9Smrg
8424fee23f9Smrg      14. Location of global variables.
8434fee23f9Smrg      All global variables of class type, whether in the "user visible"
84448fb7bfaSmrg      space (e.g., <code>cin</code>) or the implementation namespace, must be defined
8454fee23f9Smrg      as a character array with the appropriate alignment and then later
8464fee23f9Smrg      re-initialized to the correct value.
8474fee23f9Smrg
8484fee23f9Smrg      This is due to startup issues on certain platforms, such as AIX.
84948fb7bfaSmrg      For more explanation and examples, see <filename>src/globals.cc</filename>. All such
8504fee23f9Smrg      variables should be contained in that file, for simplicity.
8514fee23f9Smrg
8524fee23f9Smrg      15. Exception abstractions
85348fb7bfaSmrg      Use the exception abstractions found in <filename class="headerfile">functexcept.h</filename>, which allow
85448fb7bfaSmrg      C++ programmers to use this library with <literal>-fno-exceptions</literal>.  (Even if
8554fee23f9Smrg      that is rarely advisable, it's a necessary evil for backwards
8564fee23f9Smrg      compatibility.)
8574fee23f9Smrg
8584fee23f9Smrg      16. Exception error messages
8594fee23f9Smrg      All start with the name of the function where the exception is
8604fee23f9Smrg      thrown, and then (optional) descriptive text is added. Example:
8614fee23f9Smrg
86248fb7bfaSmrg      <code>
8634fee23f9Smrg      __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
86448fb7bfaSmrg      </code>
8654fee23f9Smrg
86648fb7bfaSmrg      Reason: The verbose terminate handler prints out <code>exception::what()</code>,
8674fee23f9Smrg      as well as the typeinfo for the thrown exception. As this is the
8684fee23f9Smrg      default terminate handler, by putting location info into the
8694fee23f9Smrg      exception string, a very useful error message is printed out for
8704fee23f9Smrg      uncaught exceptions. So useful, in fact, that non-programmers can
8714fee23f9Smrg      give useful error messages, and programmers can intelligently
8724fee23f9Smrg      speculate what went wrong without even using a debugger.
8734fee23f9Smrg
8744fee23f9Smrg      17. The doxygen style guide to comments is a separate document,
8754fee23f9Smrg      see index.
8764fee23f9Smrg
8774fee23f9Smrg      The library currently has a mixture of GNU-C and modern C++ coding
8784fee23f9Smrg      styles. The GNU C usages will be combed out gradually.
8794fee23f9Smrg
8804fee23f9Smrg      Name patterns:
8814fee23f9Smrg
8824fee23f9Smrg      For nonstandard names appearing in Standard headers, we are constrained
8834fee23f9Smrg      to use names that begin with underscores. This is called "uglification".
8844fee23f9Smrg      The convention is:
8854fee23f9Smrg
88648fb7bfaSmrg      Local and argument names:  <literal>__[a-z].*</literal>
8874fee23f9Smrg
88848fb7bfaSmrg      Examples:  <code>__count  __ix  __s1</code>
8894fee23f9Smrg
89048fb7bfaSmrg      Type names and template formal-argument names: <literal>_[A-Z][^_].*</literal>
8914fee23f9Smrg
89248fb7bfaSmrg      Examples:  <code>_Helper  _CharT  _N</code>
8934fee23f9Smrg
89448fb7bfaSmrg      Member data and function names: <literal>_M_.*</literal>
8954fee23f9Smrg
89648fb7bfaSmrg      Examples:  <code>_M_num_elements  _M_initialize ()</code>
8974fee23f9Smrg
89848fb7bfaSmrg      Static data members, constants, and enumerations: <literal>_S_.*</literal>
8994fee23f9Smrg
90048fb7bfaSmrg      Examples: <code>_S_max_elements  _S_default_value</code>
9014fee23f9Smrg
9024fee23f9Smrg      Don't use names in the same scope that differ only in the prefix,
9033f4ceed9Smrg      e.g. _S_top and _M_top. See <link linkend="coding_style.bad_identifiers">BADNAMES</link> for a list of forbidden names.
9044fee23f9Smrg      (The most tempting of these seem to be and "_T" and "__sz".)
9054fee23f9Smrg
9064fee23f9Smrg      Names must never have "__" internally; it would confuse name
9074fee23f9Smrg      unmanglers on some targets. Also, never use "__[0-9]", same reason.
9084fee23f9Smrg
9094fee23f9Smrg      --------------------------
9104fee23f9Smrg
9114fee23f9Smrg      [BY EXAMPLE]
91248fb7bfaSmrg      <code>
9134fee23f9Smrg
9144fee23f9Smrg      #ifndef  _HEADER_
9154fee23f9Smrg      #define  _HEADER_ 1
9164fee23f9Smrg
9174fee23f9Smrg      namespace std
9184fee23f9Smrg      {
9194fee23f9Smrg        class gribble
9204fee23f9Smrg        {
9214fee23f9Smrg        public:
9224fee23f9Smrg          gribble() throw();
9234fee23f9Smrg
9244fee23f9Smrg          gribble(const gribble&amp;);
9254fee23f9Smrg
9264fee23f9Smrg          explicit
9274fee23f9Smrg          gribble(int __howmany);
9284fee23f9Smrg
9294fee23f9Smrg          gribble&amp;
9304fee23f9Smrg          operator=(const gribble&amp;);
9314fee23f9Smrg
9324fee23f9Smrg          virtual
9334fee23f9Smrg          ~gribble() throw ();
9344fee23f9Smrg
9354fee23f9Smrg          // Start with a capital letter, end with a period.
9364fee23f9Smrg          inline void
9374fee23f9Smrg          public_member(const char* __arg) const;
9384fee23f9Smrg
9394fee23f9Smrg          // In-class function definitions should be restricted to one-liners.
9404fee23f9Smrg          int
9414fee23f9Smrg          one_line() { return 0 }
9424fee23f9Smrg
9434fee23f9Smrg          int
9444fee23f9Smrg          two_lines(const char* arg)
9454fee23f9Smrg          { return strchr(arg, 'a'); }
9464fee23f9Smrg
9474fee23f9Smrg          inline int
9484fee23f9Smrg          three_lines();  // inline, but defined below.
9494fee23f9Smrg
9504fee23f9Smrg          // Note indentation.
9514fee23f9Smrg          template&lt;typename _Formal_argument&gt;
9524fee23f9Smrg            void
9534fee23f9Smrg            public_template() const throw();
9544fee23f9Smrg
9554fee23f9Smrg          template&lt;typename _Iterator&gt;
9564fee23f9Smrg            void
9574fee23f9Smrg            other_template();
9584fee23f9Smrg
9594fee23f9Smrg        private:
9604fee23f9Smrg          class _Helper;
9614fee23f9Smrg
9624fee23f9Smrg          int _M_private_data;
9634fee23f9Smrg          int _M_more_stuff;
9644fee23f9Smrg          _Helper* _M_helper;
9654fee23f9Smrg          int _M_private_function();
9664fee23f9Smrg
9674fee23f9Smrg          enum _Enum
9684fee23f9Smrg            {
9694fee23f9Smrg              _S_one,
9704fee23f9Smrg              _S_two
9714fee23f9Smrg            };
9724fee23f9Smrg
9734fee23f9Smrg          static void
9744fee23f9Smrg          _S_initialize_library();
9754fee23f9Smrg        };
9764fee23f9Smrg
9774fee23f9Smrg        // More-or-less-standard language features described by lack, not presence.
9784fee23f9Smrg      # ifndef _G_NO_LONGLONG
9794fee23f9Smrg        extern long long _G_global_with_a_good_long_name;  // avoid globals!
9804fee23f9Smrg      # endif
9814fee23f9Smrg
9824fee23f9Smrg        // Avoid in-class inline definitions, define separately;
9834fee23f9Smrg        // likewise for member class definitions:
9844fee23f9Smrg        inline int
9854fee23f9Smrg        gribble::public_member() const
9864fee23f9Smrg        { int __local = 0; return __local; }
9874fee23f9Smrg
9884fee23f9Smrg        class gribble::_Helper
9894fee23f9Smrg        {
9904fee23f9Smrg          int _M_stuff;
9914fee23f9Smrg
9924fee23f9Smrg          friend class gribble;
9934fee23f9Smrg        };
9944fee23f9Smrg      }
9954fee23f9Smrg
9964fee23f9Smrg      // Names beginning with "__": only for arguments and
9974fee23f9Smrg      //   local variables; never use "__" in a type name, or
9984fee23f9Smrg      //   within any name; never use "__[0-9]".
9994fee23f9Smrg
10004fee23f9Smrg      #endif /* _HEADER_ */
10014fee23f9Smrg
10024fee23f9Smrg
10034fee23f9Smrg      namespace std
10044fee23f9Smrg      {
10054fee23f9Smrg        template&lt;typename T&gt;  // notice: "typename", not "class", no space
10064fee23f9Smrg          long_return_value_type&lt;with_many, args&gt;
10074fee23f9Smrg          function_name(char* pointer,               // "char *pointer" is wrong.
10084fee23f9Smrg                        char* argument,
10094fee23f9Smrg                        const Reference&amp; ref)
10104fee23f9Smrg          {
10114fee23f9Smrg            // int a_local;  /* wrong; see below. */
10124fee23f9Smrg            if (test)
10134fee23f9Smrg            {
10144fee23f9Smrg              nested code
10154fee23f9Smrg            }
10164fee23f9Smrg
10174fee23f9Smrg            int a_local = 0;  // declare variable at first use.
10184fee23f9Smrg
10194fee23f9Smrg            //  char a, b, *p;   /* wrong */
10204fee23f9Smrg            char a = 'a';
10214fee23f9Smrg            char b = a + 1;
10224fee23f9Smrg            char* c = "abc";  // each variable goes on its own line, always.
10234fee23f9Smrg
10244fee23f9Smrg            // except maybe here...
10254fee23f9Smrg            for (unsigned i = 0, mask = 1; mask; ++i, mask &lt;&lt;= 1) {
10264fee23f9Smrg              // ...
10274fee23f9Smrg            }
10284fee23f9Smrg          }
10294fee23f9Smrg
10304fee23f9Smrg        gribble::gribble()
103148fb7bfaSmrg        : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
10324fee23f9Smrg        { }
10334fee23f9Smrg
103448fb7bfaSmrg        int
10354fee23f9Smrg        gribble::three_lines()
10364fee23f9Smrg        {
10374fee23f9Smrg          // doesn't fit in one line.
10384fee23f9Smrg        }
10394fee23f9Smrg      } // namespace std
104048fb7bfaSmrg      </code>
10414fee23f9Smrg    </literallayout>
104248fb7bfaSmrg  </section>
104348fb7bfaSmrg</section>
10444fee23f9Smrg
104548fb7bfaSmrg<section xml:id="contrib.design_notes" xreflabel="Design Notes"><info><title>Design Notes</title></info>
10464fee23f9Smrg  <?dbhtml filename="source_design_notes.html"?>
104748fb7bfaSmrg
10484fee23f9Smrg  <para>
10494fee23f9Smrg  </para>
10504fee23f9Smrg
105148fb7bfaSmrg  <literallayout class="normal">
10524fee23f9Smrg
10534fee23f9Smrg    The Library
10544fee23f9Smrg    -----------
10554fee23f9Smrg
10564fee23f9Smrg    This paper is covers two major areas:
10574fee23f9Smrg
10584fee23f9Smrg    - Features and policies not mentioned in the standard that
10594fee23f9Smrg    the quality of the library implementation depends on, including
10604fee23f9Smrg    extensions and "implementation-defined" features;
10614fee23f9Smrg
10624fee23f9Smrg    - Plans for required but unimplemented library features and
10634fee23f9Smrg    optimizations to them.
10644fee23f9Smrg
10654fee23f9Smrg    Overhead
10664fee23f9Smrg    --------
10674fee23f9Smrg
10684fee23f9Smrg    The standard defines a large library, much larger than the standard
10694fee23f9Smrg    C library. A naive implementation would suffer substantial overhead
10704fee23f9Smrg    in compile time, executable size, and speed, rendering it unusable
10714fee23f9Smrg    in many (particularly embedded) applications. The alternative demands
10724fee23f9Smrg    care in construction, and some compiler support, but there is no
10734fee23f9Smrg    need for library subsets.
10744fee23f9Smrg
10754fee23f9Smrg    What are the sources of this overhead?  There are four main causes:
10764fee23f9Smrg
10774fee23f9Smrg    - The library is specified almost entirely as templates, which
10784fee23f9Smrg    with current compilers must be included in-line, resulting in
10794fee23f9Smrg    very slow builds as tens or hundreds of thousands of lines
10804fee23f9Smrg    of function definitions are read for each user source file.
10814fee23f9Smrg    Indeed, the entire SGI STL, as well as the dos Reis valarray,
10824fee23f9Smrg    are provided purely as header files, largely for simplicity in
10834fee23f9Smrg    porting. Iostream/locale is (or will be) as large again.
10844fee23f9Smrg
10854fee23f9Smrg    - The library is very flexible, specifying a multitude of hooks
10864fee23f9Smrg    where users can insert their own code in place of defaults.
10874fee23f9Smrg    When these hooks are not used, any time and code expended to
10884fee23f9Smrg    support that flexibility is wasted.
10894fee23f9Smrg
10904fee23f9Smrg    - Templates are often described as causing to "code bloat". In
10914fee23f9Smrg    practice, this refers (when it refers to anything real) to several
10924fee23f9Smrg    independent processes. First, when a class template is manually
10934fee23f9Smrg    instantiated in its entirely, current compilers place the definitions
10944fee23f9Smrg    for all members in a single object file, so that a program linking
10954fee23f9Smrg    to one member gets definitions of all. Second, template functions
10964fee23f9Smrg    which do not actually depend on the template argument are, under
10974fee23f9Smrg    current compilers, generated anew for each instantiation, rather
10984fee23f9Smrg    than being shared with other instantiations. Third, some of the
10994fee23f9Smrg    flexibility mentioned above comes from virtual functions (both in
11004fee23f9Smrg    regular classes and template classes) which current linkers add
11014fee23f9Smrg    to the executable file even when they manifestly cannot be called.
11024fee23f9Smrg
11034fee23f9Smrg    - The library is specified to use a language feature, exceptions,
11044fee23f9Smrg    which in the current gcc compiler ABI imposes a run time and
11054fee23f9Smrg    code space cost to handle the possibility of exceptions even when
11064fee23f9Smrg    they are not used. Under the new ABI (accessed with -fnew-abi),
11074fee23f9Smrg    there is a space overhead and a small reduction in code efficiency
11084fee23f9Smrg    resulting from lost optimization opportunities associated with
11094fee23f9Smrg    non-local branches associated with exceptions.
11104fee23f9Smrg
11114fee23f9Smrg    What can be done to eliminate this overhead?  A variety of coding
11124fee23f9Smrg    techniques, and compiler, linker and library improvements and
11134fee23f9Smrg    extensions may be used, as covered below. Most are not difficult,
11144fee23f9Smrg    and some are already implemented in varying degrees.
11154fee23f9Smrg
11164fee23f9Smrg    Overhead: Compilation Time
11174fee23f9Smrg    --------------------------
11184fee23f9Smrg
11194fee23f9Smrg    Providing "ready-instantiated" template code in object code archives
11204fee23f9Smrg    allows us to avoid generating and optimizing template instantiations
11214fee23f9Smrg    in each compilation unit which uses them. However, the number of such
11224fee23f9Smrg    instantiations that are useful to provide is limited, and anyway this
11234fee23f9Smrg    is not enough, by itself, to minimize compilation time. In particular,
11244fee23f9Smrg    it does not reduce time spent parsing conforming headers.
11254fee23f9Smrg
11264fee23f9Smrg    Quicker header parsing will depend on library extensions and compiler
11274fee23f9Smrg    improvements.  One approach is some variation on the techniques
11284fee23f9Smrg    previously marketed as "pre-compiled headers", now standardized as
11294fee23f9Smrg    support for the "export" keyword. "Exported" template definitions
11304fee23f9Smrg    can be placed (once) in a "repository" -- really just a library, but
11314fee23f9Smrg    of template definitions rather than object code -- to be drawn upon
11324fee23f9Smrg    at link time when an instantiation is needed, rather than placed in
11334fee23f9Smrg    header files to be parsed along with every compilation unit.
11344fee23f9Smrg
11354fee23f9Smrg    Until "export" is implemented we can put some of the lengthy template
11364fee23f9Smrg    definitions in #if guards or alternative headers so that users can skip
11374fee23f9Smrg    over the full definitions when they need only the ready-instantiated
11384fee23f9Smrg    specializations.
11394fee23f9Smrg
11404fee23f9Smrg    To be precise, this means that certain headers which define
11414fee23f9Smrg    templates which users normally use only for certain arguments
11424fee23f9Smrg    can be instrumented to avoid exposing the template definitions
11434fee23f9Smrg    to the compiler unless a macro is defined. For example, in
11444fee23f9Smrg    &lt;string&gt;, we might have:
11454fee23f9Smrg
11464fee23f9Smrg    template &lt;class _CharT, ... &gt; class basic_string {
11474fee23f9Smrg    ... // member declarations
11484fee23f9Smrg    };
11494fee23f9Smrg    ... // operator declarations
11504fee23f9Smrg
11514fee23f9Smrg    #ifdef _STRICT_ISO_
11524fee23f9Smrg    # if _G_NO_TEMPLATE_EXPORT
11534fee23f9Smrg    #   include &lt;bits/std_locale.h&gt;  // headers needed by definitions
11544fee23f9Smrg    #   ...
11554fee23f9Smrg    #   include &lt;bits/string.tcc&gt;  // member and global template definitions.
11564fee23f9Smrg    # endif
11574fee23f9Smrg    #endif
11584fee23f9Smrg
11594fee23f9Smrg    Users who compile without specifying a strict-ISO-conforming flag
11604fee23f9Smrg    would not see many of the template definitions they now see, and rely
11614fee23f9Smrg    instead on ready-instantiated specializations in the library. This
11624fee23f9Smrg    technique would be useful for the following substantial components:
11634fee23f9Smrg    string, locale/iostreams, valarray. It would *not* be useful or
11644fee23f9Smrg    usable with the following: containers, algorithms, iterators,
11654fee23f9Smrg    allocator. Since these constitute a large (though decreasing)
11664fee23f9Smrg    fraction of the library, the benefit the technique offers is
11674fee23f9Smrg    limited.
11684fee23f9Smrg
11694fee23f9Smrg    The language specifies the semantics of the "export" keyword, but
11704fee23f9Smrg    the gcc compiler does not yet support it. When it does, problems
11714fee23f9Smrg    with large template inclusions can largely disappear, given some
11724fee23f9Smrg    minor library reorganization, along with the need for the apparatus
11734fee23f9Smrg    described above.
11744fee23f9Smrg
11754fee23f9Smrg    Overhead: Flexibility Cost
11764fee23f9Smrg    --------------------------
11774fee23f9Smrg
11784fee23f9Smrg    The library offers many places where users can specify operations
11794fee23f9Smrg    to be performed by the library in place of defaults. Sometimes
11804fee23f9Smrg    this seems to require that the library use a more-roundabout, and
11814fee23f9Smrg    possibly slower, way to accomplish the default requirements than
11824fee23f9Smrg    would be used otherwise.
11834fee23f9Smrg
11844fee23f9Smrg    The primary protection against this overhead is thorough compiler
11854fee23f9Smrg    optimization, to crush out layers of inline function interfaces.
11864fee23f9Smrg    Kuck &amp; Associates has demonstrated the practicality of this kind
11874fee23f9Smrg    of optimization.
11884fee23f9Smrg
11894fee23f9Smrg    The second line of defense against this overhead is explicit
11904fee23f9Smrg    specialization. By defining helper function templates, and writing
11914fee23f9Smrg    specialized code for the default case, overhead can be eliminated
11924fee23f9Smrg    for that case without sacrificing flexibility. This takes full
11934fee23f9Smrg    advantage of any ability of the optimizer to crush out degenerate
11944fee23f9Smrg    code.
11954fee23f9Smrg
11964fee23f9Smrg    The library specifies many virtual functions which current linkers
11974fee23f9Smrg    load even when they cannot be called. Some minor improvements to the
11984fee23f9Smrg    compiler and to ld would eliminate any such overhead by simply
11994fee23f9Smrg    omitting virtual functions that the complete program does not call.
12004fee23f9Smrg    A prototype of this work has already been done. For targets where
12014fee23f9Smrg    GNU ld is not used, a "pre-linker" could do the same job.
12024fee23f9Smrg
12034fee23f9Smrg    The main areas in the standard interface where user flexibility
12044fee23f9Smrg    can result in overhead are:
12054fee23f9Smrg
12064fee23f9Smrg    - Allocators:  Containers are specified to use user-definable
12074fee23f9Smrg    allocator types and objects, making tuning for the container
12084fee23f9Smrg    characteristics tricky.
12094fee23f9Smrg
12104fee23f9Smrg    - Locales: the standard specifies locale objects used to implement
12114fee23f9Smrg    iostream operations, involving many virtual functions which use
12124fee23f9Smrg    streambuf iterators.
12134fee23f9Smrg
12144fee23f9Smrg    - Algorithms and containers: these may be instantiated on any type,
12154fee23f9Smrg    frequently duplicating code for identical operations.
12164fee23f9Smrg
12174fee23f9Smrg    - Iostreams and strings: users are permitted to use these on their
12184fee23f9Smrg    own types, and specify the operations the stream must use on these
12194fee23f9Smrg    types.
12204fee23f9Smrg
12214fee23f9Smrg    Note that these sources of overhead are _avoidable_. The techniques
12224fee23f9Smrg    to avoid them are covered below.
12234fee23f9Smrg
12244fee23f9Smrg    Code Bloat
12254fee23f9Smrg    ----------
12264fee23f9Smrg
12274fee23f9Smrg    In the SGI STL, and in some other headers, many of the templates
12284fee23f9Smrg    are defined "inline" -- either explicitly or by their placement
12294fee23f9Smrg    in class definitions -- which should not be inline. This is a
12304fee23f9Smrg    source of code bloat. Matt had remarked that he was relying on
12314fee23f9Smrg    the compiler to recognize what was too big to benefit from inlining,
12324fee23f9Smrg    and generate it out-of-line automatically. However, this also can
12334fee23f9Smrg    result in code bloat except where the linker can eliminate the extra
12344fee23f9Smrg    copies.
12354fee23f9Smrg
12364fee23f9Smrg    Fixing these cases will require an audit of all inline functions
12374fee23f9Smrg    defined in the library to determine which merit inlining, and moving
12384d5abbe8Smrg    the rest out of line. This is an issue mainly in clauses 23, 25, and
12394fee23f9Smrg    27. Of course it can be done incrementally, and we should generally
12404fee23f9Smrg    accept patches that move large functions out of line and into ".tcc"
12414fee23f9Smrg    files, which can later be pulled into a repository. Compiler/linker
12424fee23f9Smrg    improvements to recognize very large inline functions and move them
12434fee23f9Smrg    out-of-line, but shared among compilation units, could make this
12444fee23f9Smrg    work unnecessary.
12454fee23f9Smrg
12464fee23f9Smrg    Pre-instantiating template specializations currently produces large
12474fee23f9Smrg    amounts of dead code which bloats statically linked programs. The
12484fee23f9Smrg    current state of the static library, libstdc++.a, is intolerable on
12494fee23f9Smrg    this account, and will fuel further confused speculation about a need
12504fee23f9Smrg    for a library "subset". A compiler improvement that treats each
12514fee23f9Smrg    instantiated function as a separate object file, for linking purposes,
12524fee23f9Smrg    would be one solution to this problem. An alternative would be to
12534fee23f9Smrg    split up the manual instantiation files into dozens upon dozens of
12544fee23f9Smrg    little files, each compiled separately, but an abortive attempt at
12554fee23f9Smrg    this was done for &lt;string&gt; and, though it is far from complete, it
12564fee23f9Smrg    is already a nuisance. A better interim solution (just until we have
12574fee23f9Smrg    "export") is badly needed.
12584fee23f9Smrg
12594fee23f9Smrg    When building a shared library, the current compiler/linker cannot
12604fee23f9Smrg    automatically generate the instantiations needed. This creates a
12614fee23f9Smrg    miserable situation; it means any time something is changed in the
12624fee23f9Smrg    library, before a shared library can be built someone must manually
12634fee23f9Smrg    copy the declarations of all templates that are needed by other parts
12644fee23f9Smrg    of the library to an "instantiation" file, and add it to the build
12654fee23f9Smrg    system to be compiled and linked to the library. This process is
12664fee23f9Smrg    readily automated, and should be automated as soon as possible.
12674fee23f9Smrg    Users building their own shared libraries experience identical
12684fee23f9Smrg    frustrations.
12694fee23f9Smrg
12704fee23f9Smrg    Sharing common aspects of template definitions among instantiations
12714fee23f9Smrg    can radically reduce code bloat. The compiler could help a great
12724fee23f9Smrg    deal here by recognizing when a function depends on nothing about
12734fee23f9Smrg    a template parameter, or only on its size, and giving the resulting
12744fee23f9Smrg    function a link-name "equate" that allows it to be shared with other
12754fee23f9Smrg    instantiations. Implementation code could take advantage of the
12764fee23f9Smrg    capability by factoring out code that does not depend on the template
12774fee23f9Smrg    argument into separate functions to be merged by the compiler.
12784fee23f9Smrg
12794fee23f9Smrg    Until such a compiler optimization is implemented, much can be done
12804fee23f9Smrg    manually (if tediously) in this direction. One such optimization is
12814fee23f9Smrg    to derive class templates from non-template classes, and move as much
12824fee23f9Smrg    implementation as possible into the base class. Another is to partial-
12834fee23f9Smrg    specialize certain common instantiations, such as vector&lt;T*&gt;, to share
12844fee23f9Smrg    code for instantiations on all types T. While these techniques work,
12854fee23f9Smrg    they are far from the complete solution that a compiler improvement
12864fee23f9Smrg    would afford.
12874fee23f9Smrg
12884fee23f9Smrg    Overhead: Expensive Language Features
12894fee23f9Smrg    -------------------------------------
12904fee23f9Smrg
12914fee23f9Smrg    The main "expensive" language feature used in the standard library
12924fee23f9Smrg    is exception support, which requires compiling in cleanup code with
12934fee23f9Smrg    static table data to locate it, and linking in library code to use
12944fee23f9Smrg    the table. For small embedded programs the amount of such library
12954fee23f9Smrg    code and table data is assumed by some to be excessive. Under the
12964fee23f9Smrg    "new" ABI this perception is generally exaggerated, although in some
12974fee23f9Smrg    cases it may actually be excessive.
12984fee23f9Smrg
12994fee23f9Smrg    To implement a library which does not use exceptions directly is
13004fee23f9Smrg    not difficult given minor compiler support (to "turn off" exceptions
13014fee23f9Smrg    and ignore exception constructs), and results in no great library
13024fee23f9Smrg    maintenance difficulties. To be precise, given "-fno-exceptions",
13034fee23f9Smrg    the compiler should treat "try" blocks as ordinary blocks, and
13044fee23f9Smrg    "catch" blocks as dead code to ignore or eliminate. Compiler
13054fee23f9Smrg    support is not strictly necessary, except in the case of "function
13064fee23f9Smrg    try blocks"; otherwise the following macros almost suffice:
13074fee23f9Smrg
13084fee23f9Smrg    #define throw(X)
13094fee23f9Smrg    #define try      if (true)
13104fee23f9Smrg    #define catch(X) else if (false)
13114fee23f9Smrg
13124fee23f9Smrg    However, there may be a need to use function try blocks in the
13134fee23f9Smrg    library implementation, and use of macros in this way can make
13144fee23f9Smrg    correct diagnostics impossible. Furthermore, use of this scheme
13154fee23f9Smrg    would require the library to call a function to re-throw exceptions
13164fee23f9Smrg    from a try block. Implementing the above semantics in the compiler
13174fee23f9Smrg    is preferable.
13184fee23f9Smrg
13194fee23f9Smrg    Given the support above (however implemented) it only remains to
13204fee23f9Smrg    replace code that "throws" with a call to a well-documented "handler"
13214fee23f9Smrg    function in a separate compilation unit which may be replaced by
13224fee23f9Smrg    the user. The main source of exceptions that would be difficult
13234fee23f9Smrg    for users to avoid is memory allocation failures, but users can
13244fee23f9Smrg    define their own memory allocation primitives that never throw.
13254fee23f9Smrg    Otherwise, the complete list of such handlers, and which library
13264fee23f9Smrg    functions may call them, would be needed for users to be able to
13274fee23f9Smrg    implement the necessary substitutes. (Fortunately, they have the
13284fee23f9Smrg    source code.)
13294fee23f9Smrg
13304fee23f9Smrg    Opportunities
13314fee23f9Smrg    -------------
13324fee23f9Smrg
13334fee23f9Smrg    The template capabilities of C++ offer enormous opportunities for
13344fee23f9Smrg    optimizing common library operations, well beyond what would be
13354fee23f9Smrg    considered "eliminating overhead". In particular, many operations
13364fee23f9Smrg    done in Glibc with macros that depend on proprietary language
13374fee23f9Smrg    extensions can be implemented in pristine Standard C++. For example,
13384fee23f9Smrg    the chapter 25 algorithms, and even C library functions such as strchr,
13394fee23f9Smrg    can be specialized for the case of static arrays of known (small) size.
13404fee23f9Smrg
13414fee23f9Smrg    Detailed optimization opportunities are identified below where
13424fee23f9Smrg    the component where they would appear is discussed. Of course new
13434fee23f9Smrg    opportunities will be identified during implementation.
13444fee23f9Smrg
13454fee23f9Smrg    Unimplemented Required Library Features
13464fee23f9Smrg    ---------------------------------------
13474fee23f9Smrg
13484fee23f9Smrg    The standard specifies hundreds of components, grouped broadly by
13494fee23f9Smrg    chapter. These are listed in excruciating detail in the CHECKLIST
13504fee23f9Smrg    file.
13514fee23f9Smrg
13524fee23f9Smrg    17 general
13534fee23f9Smrg    18 support
13544fee23f9Smrg    19 diagnostics
13554fee23f9Smrg    20 utilities
13564fee23f9Smrg    21 string
13574fee23f9Smrg    22 locale
13584fee23f9Smrg    23 containers
13594fee23f9Smrg    24 iterators
13604fee23f9Smrg    25 algorithms
13614fee23f9Smrg    26 numerics
13624fee23f9Smrg    27 iostreams
13634fee23f9Smrg    Annex D  backward compatibility
13644fee23f9Smrg
13654fee23f9Smrg    Anyone participating in implementation of the library should obtain
13664fee23f9Smrg    a copy of the standard, ISO 14882.  People in the U.S. can obtain an
13674fee23f9Smrg    electronic copy for US$18 from ANSI's web site. Those from other
13684fee23f9Smrg    countries should visit http://www.iso.org/ to find out the location
13694fee23f9Smrg    of their country's representation in ISO, in order to know who can
13704fee23f9Smrg    sell them a copy.
13714fee23f9Smrg
13724fee23f9Smrg    The emphasis in the following sections is on unimplemented features
13734fee23f9Smrg    and optimization opportunities.
13744fee23f9Smrg
13754fee23f9Smrg    Chapter 17  General
13764fee23f9Smrg    -------------------
13774fee23f9Smrg
13784fee23f9Smrg    Chapter 17 concerns overall library requirements.
13794fee23f9Smrg
13804fee23f9Smrg    The standard doesn't mention threads. A multi-thread (MT) extension
13814fee23f9Smrg    primarily affects operators new and delete (18), allocator (20),
13824fee23f9Smrg    string (21), locale (22), and iostreams (27). The common underlying
13834fee23f9Smrg    support needed for this is discussed under chapter 20.
13844fee23f9Smrg
13854fee23f9Smrg    The standard requirements on names from the C headers create a
13864fee23f9Smrg    lot of work, mostly done. Names in the C headers must be visible
13874fee23f9Smrg    in the std:: and sometimes the global namespace; the names in the
13884fee23f9Smrg    two scopes must refer to the same object. More stringent is that
13894fee23f9Smrg    Koenig lookup implies that any types specified as defined in std::
13904fee23f9Smrg    really are defined in std::. Names optionally implemented as
13914fee23f9Smrg    macros in C cannot be macros in C++. (An overview may be read at
13924fee23f9Smrg    &lt;http://www.cantrip.org/cheaders.html&gt;). The scripts "inclosure"
13934fee23f9Smrg    and "mkcshadow", and the directories shadow/ and cshadow/, are the
13944fee23f9Smrg    beginning of an effort to conform in this area.
13954fee23f9Smrg
13964fee23f9Smrg    A correct conforming definition of C header names based on underlying
13974fee23f9Smrg    C library headers, and practical linking of conforming namespaced
13984fee23f9Smrg    customer code with third-party C libraries depends ultimately on
13994fee23f9Smrg    an ABI change, allowing namespaced C type names to be mangled into
14004fee23f9Smrg    type names as if they were global, somewhat as C function names in a
14014fee23f9Smrg    namespace, or C++ global variable names, are left unmangled. Perhaps
14024fee23f9Smrg    another "extern" mode, such as 'extern "C-global"' would be an
14034fee23f9Smrg    appropriate place for such type definitions. Such a type would
14044fee23f9Smrg    affect mangling as follows:
14054fee23f9Smrg
14064fee23f9Smrg    namespace A {
14074fee23f9Smrg    struct X {};
14084fee23f9Smrg    extern "C-global" {  // or maybe just 'extern "C"'
14094fee23f9Smrg    struct Y {};
14104fee23f9Smrg    };
14114fee23f9Smrg    }
14124fee23f9Smrg    void f(A::X*);  // mangles to f__FPQ21A1X
14134fee23f9Smrg    void f(A::Y*);  // mangles to f__FP1Y
14144fee23f9Smrg
14154fee23f9Smrg    (It may be that this is really the appropriate semantics for regular
14164fee23f9Smrg    'extern "C"', and 'extern "C-global"', as an extension, would not be
14174fee23f9Smrg    necessary.) This would allow functions declared in non-standard C headers
14184fee23f9Smrg    (and thus fixable by neither us nor users) to link properly with functions
14194fee23f9Smrg    declared using C types defined in properly-namespaced headers. The
14204fee23f9Smrg    problem this solves is that C headers (which C++ programmers do persist
14214fee23f9Smrg    in using) frequently forward-declare C struct tags without including
14224fee23f9Smrg    the header where the type is defined, as in
14234fee23f9Smrg
14244fee23f9Smrg    struct tm;
14254fee23f9Smrg    void munge(tm*);
14264fee23f9Smrg
14274fee23f9Smrg    Without some compiler accommodation, munge cannot be called by correct
14284fee23f9Smrg    C++ code using a pointer to a correctly-scoped tm* value.
14294fee23f9Smrg
14304fee23f9Smrg    The current C headers use the preprocessor extension "#include_next",
14314fee23f9Smrg    which the compiler complains about when run "-pedantic".
14324fee23f9Smrg    (Incidentally, it appears that "-fpedantic" is currently ignored,
14334fee23f9Smrg    probably a bug.)  The solution in the C compiler is to use
14344fee23f9Smrg    "-isystem" rather than "-I", but unfortunately in g++ this seems
14354fee23f9Smrg    also to wrap the whole header in an 'extern "C"' block, so it's
14364fee23f9Smrg    unusable for C++ headers. The correct solution appears to be to
14374fee23f9Smrg    allow the various special include-directory options, if not given
14384fee23f9Smrg    an argument, to affect subsequent include-directory options additively,
14394fee23f9Smrg    so that if one said
14404fee23f9Smrg
14414fee23f9Smrg    -pedantic -iprefix $(prefix) \
14424fee23f9Smrg    -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \
14434fee23f9Smrg    -iwithprefix -I g++-v3/ext
14444fee23f9Smrg
14454fee23f9Smrg    the compiler would search $(prefix)/g++-v3 and not report
14464fee23f9Smrg    pedantic warnings for files found there, but treat files in
14474fee23f9Smrg    $(prefix)/g++-v3/ext pedantically. (The undocumented semantics
14484fee23f9Smrg    of "-isystem" in g++ stink. Can they be rescinded?  If not it
14494fee23f9Smrg    must be replaced with something more rationally behaved.)
14504fee23f9Smrg
14514fee23f9Smrg    All the C headers need the treatment above; in the standard these
14524d5abbe8Smrg    headers are mentioned in various clauses. Below, I have only
14534fee23f9Smrg    mentioned those that present interesting implementation issues.
14544fee23f9Smrg
14554fee23f9Smrg    The components identified as "mostly complete", below, have not been
14564fee23f9Smrg    audited for conformance. In many cases where the library passes
14574fee23f9Smrg    conformance tests we have non-conforming extensions that must be
14584fee23f9Smrg    wrapped in #if guards for "pedantic" use, and in some cases renamed
14594fee23f9Smrg    in a conforming way for continued use in the implementation regardless
14604fee23f9Smrg    of conformance flags.
14614fee23f9Smrg
14624fee23f9Smrg    The STL portion of the library still depends on a header
14634fee23f9Smrg    stl/bits/stl_config.h full of #ifdef clauses. This apparatus
14644fee23f9Smrg    should be replaced with autoconf/automake machinery.
14654fee23f9Smrg
14664fee23f9Smrg    The SGI STL defines a type_traits&lt;&gt; template, specialized for
14674fee23f9Smrg    many types in their code including the built-in numeric and
14684fee23f9Smrg    pointer types and some library types, to direct optimizations of
14694fee23f9Smrg    standard functions. The SGI compiler has been extended to generate
14704fee23f9Smrg    specializations of this template automatically for user types,
14714fee23f9Smrg    so that use of STL templates on user types can take advantage of
14724fee23f9Smrg    these optimizations. Specializations for other, non-STL, types
14734fee23f9Smrg    would make more optimizations possible, but extending the gcc
14744fee23f9Smrg    compiler in the same way would be much better. Probably the next
14754fee23f9Smrg    round of standardization will ratify this, but probably with
14764fee23f9Smrg    changes, so it probably should be renamed to place it in the
14774fee23f9Smrg    implementation namespace.
14784fee23f9Smrg
14794fee23f9Smrg    The SGI STL also defines a large number of extensions visible in
14804fee23f9Smrg    standard headers. (Other extensions that appear in separate headers
14814fee23f9Smrg    have been sequestered in subdirectories ext/ and backward/.)  All
14824fee23f9Smrg    these extensions should be moved to other headers where possible,
14834fee23f9Smrg    and in any case wrapped in a namespace (not std!), and (where kept
14844fee23f9Smrg    in a standard header) girded about with macro guards. Some cannot be
14854fee23f9Smrg    moved out of standard headers because they are used to implement
14864fee23f9Smrg    standard features.  The canonical method for accommodating these
14874fee23f9Smrg    is to use a protected name, aliased in macro guards to a user-space
14884fee23f9Smrg    name. Unfortunately C++ offers no satisfactory template typedef
14894fee23f9Smrg    mechanism, so very ad-hoc and unsatisfactory aliasing must be used
14904fee23f9Smrg    instead.
14914fee23f9Smrg
14924fee23f9Smrg    Implementation of a template typedef mechanism should have the highest
14934fee23f9Smrg    priority among possible extensions, on the same level as implementation
14944fee23f9Smrg    of the template "export" feature.
14954fee23f9Smrg
14964fee23f9Smrg    Chapter 18  Language support
14974fee23f9Smrg    ----------------------------
14984fee23f9Smrg
14994fee23f9Smrg    Headers: &lt;limits&gt; &lt;new&gt; &lt;typeinfo&gt; &lt;exception&gt;
15004fee23f9Smrg    C headers: &lt;cstddef&gt; &lt;climits&gt; &lt;cfloat&gt;  &lt;cstdarg&gt; &lt;csetjmp&gt;
15014fee23f9Smrg    &lt;ctime&gt;   &lt;csignal&gt; &lt;cstdlib&gt; (also 21, 25, 26)
15024fee23f9Smrg
15034fee23f9Smrg    This defines the built-in exceptions, rtti, numeric_limits&lt;&gt;,
15044fee23f9Smrg    operator new and delete. Much of this is provided by the
15054fee23f9Smrg    compiler in its static runtime library.
15064fee23f9Smrg
15074fee23f9Smrg    Work to do includes defining numeric_limits&lt;&gt; specializations in
15084fee23f9Smrg    separate files for all target architectures. Values for integer types
15094fee23f9Smrg    except for bool and wchar_t are readily obtained from the C header
15104fee23f9Smrg    &lt;limits.h&gt;, but values for the remaining numeric types (bool, wchar_t,
15114fee23f9Smrg    float, double, long double) must be entered manually. This is
15124fee23f9Smrg    largely dog work except for those members whose values are not
15134fee23f9Smrg    easily deduced from available documentation. Also, this involves
15144fee23f9Smrg    some work in target configuration to identify the correct choice of
15154fee23f9Smrg    file to build against and to install.
15164fee23f9Smrg
15174fee23f9Smrg    The definitions of the various operators new and delete must be
15184fee23f9Smrg    made thread-safe, which depends on a portable exclusion mechanism,
15194fee23f9Smrg    discussed under chapter 20.  Of course there is always plenty of
15204fee23f9Smrg    room for improvements to the speed of operators new and delete.
15214fee23f9Smrg
15224fee23f9Smrg    &lt;cstdarg&gt;, in Glibc, defines some macros that gcc does not allow to
15234fee23f9Smrg    be wrapped into an inline function. Probably this header will demand
15244fee23f9Smrg    attention whenever a new target is chosen. The functions atexit(),
15254fee23f9Smrg    exit(), and abort() in cstdlib have different semantics in C++, so
15264fee23f9Smrg    must be re-implemented for C++.
15274fee23f9Smrg
15284fee23f9Smrg    Chapter 19  Diagnostics
15294fee23f9Smrg    -----------------------
15304fee23f9Smrg
15314fee23f9Smrg    Headers: &lt;stdexcept&gt;
15324fee23f9Smrg    C headers: &lt;cassert&gt; &lt;cerrno&gt;
15334fee23f9Smrg
15344fee23f9Smrg    This defines the standard exception objects, which are "mostly complete".
15354fee23f9Smrg    Cygnus has a version, and now SGI provides a slightly different one.
15364fee23f9Smrg    It makes little difference which we use.
15374fee23f9Smrg
15384fee23f9Smrg    The C global name "errno", which C allows to be a variable or a macro,
15394fee23f9Smrg    is required in C++ to be a macro. For MT it must typically result in
15404fee23f9Smrg    a function call.
15414fee23f9Smrg
15424fee23f9Smrg    Chapter 20  Utilities
15434fee23f9Smrg    ---------------------
15444fee23f9Smrg    Headers: &lt;utility&gt; &lt;functional&gt; &lt;memory&gt;
15454fee23f9Smrg    C header: &lt;ctime&gt; (also in 18)
15464fee23f9Smrg
15474fee23f9Smrg    SGI STL provides "mostly complete" versions of all the components
15484fee23f9Smrg    defined in this chapter. However, the auto_ptr&lt;&gt; implementation
15494fee23f9Smrg    is known to be wrong. Furthermore, the standard definition of it
15504fee23f9Smrg    is known to be unimplementable as written. A minor change to the
15514fee23f9Smrg    standard would fix it, and auto_ptr&lt;&gt; should be adjusted to match.
15524fee23f9Smrg
15534fee23f9Smrg    Multi-threading affects the allocator implementation, and there must
15544fee23f9Smrg    be configuration/installation choices for different users' MT
15554fee23f9Smrg    requirements. Anyway, users will want to tune allocator options
15564fee23f9Smrg    to support different target conditions, MT or no.
15574fee23f9Smrg
15584fee23f9Smrg    The primitives used for MT implementation should be exposed, as an
15594fee23f9Smrg    extension, for users' own work. We need cross-CPU "mutex" support,
15604fee23f9Smrg    multi-processor shared-memory atomic integer operations, and single-
15614fee23f9Smrg    processor uninterruptible integer operations, and all three configurable
15624fee23f9Smrg    to be stubbed out for non-MT use, or to use an appropriately-loaded
15634fee23f9Smrg    dynamic library for the actual runtime environment, or statically
15644fee23f9Smrg    compiled in for cases where the target architecture is known.
15654fee23f9Smrg
15664fee23f9Smrg    Chapter 21  String
15674fee23f9Smrg    ------------------
15684fee23f9Smrg    Headers: &lt;string&gt;
15694fee23f9Smrg    C headers: &lt;cctype&gt; &lt;cwctype&gt; &lt;cstring&gt; &lt;cwchar&gt; (also in 27)
15704fee23f9Smrg    &lt;cstdlib&gt; (also in 18, 25, 26)
15714fee23f9Smrg
15724fee23f9Smrg    We have "mostly-complete" char_traits&lt;&gt; implementations. Many of the
15734fee23f9Smrg    char_traits&lt;char&gt; operations might be optimized further using existing
15744fee23f9Smrg    proprietary language extensions.
15754fee23f9Smrg
15764fee23f9Smrg    We have a "mostly-complete" basic_string&lt;&gt; implementation. The work
15774fee23f9Smrg    to manually instantiate char and wchar_t specializations in object
15784fee23f9Smrg    files to improve link-time behavior is extremely unsatisfactory,
15794fee23f9Smrg    literally tripling library-build time with no commensurate improvement
15804fee23f9Smrg    in static program link sizes. It must be redone. (Similar work is
15814d5abbe8Smrg    needed for some components in clauses 22 and 27.)
15824fee23f9Smrg
15834fee23f9Smrg    Other work needed for strings is MT-safety, as discussed under the
15844fee23f9Smrg    chapter 20 heading.
15854fee23f9Smrg
15864fee23f9Smrg    The standard C type mbstate_t from &lt;cwchar&gt; and used in char_traits&lt;&gt;
15874fee23f9Smrg    must be different in C++ than in C, because in C++ the default constructor
15884fee23f9Smrg    value mbstate_t() must be the "base" or "ground" sequence state.
15894fee23f9Smrg    (According to the likely resolution of a recently raised Core issue,
15904fee23f9Smrg    this may become unnecessary. However, there are other reasons to
15914fee23f9Smrg    use a state type not as limited as whatever the C library provides.)
15924fee23f9Smrg    If we might want to provide conversions from (e.g.) internally-
15934fee23f9Smrg    represented EUC-wide to externally-represented Unicode, or vice-
15944fee23f9Smrg    versa, the mbstate_t we choose will need to be more accommodating
15954fee23f9Smrg    than what might be provided by an underlying C library.
15964fee23f9Smrg
15974fee23f9Smrg    There remain some basic_string template-member functions which do
15984fee23f9Smrg    not overload properly with their non-template brethren. The infamous
15994fee23f9Smrg    hack akin to what was done in vector&lt;&gt; is needed, to conform to
16004fee23f9Smrg    23.1.1 para 10. The CHECKLIST items for basic_string marked 'X',
16014fee23f9Smrg    or incomplete, are so marked for this reason.
16024fee23f9Smrg
16034fee23f9Smrg    Replacing the string iterators, which currently are simple character
16044fee23f9Smrg    pointers, with class objects would greatly increase the safety of the
16054fee23f9Smrg    client interface, and also permit a "debug" mode in which range,
16064fee23f9Smrg    ownership, and validity are rigorously checked. The current use of
16074fee23f9Smrg    raw pointers as string iterators is evil. vector&lt;&gt; iterators need the
16084fee23f9Smrg    same treatment. Note that the current implementation freely mixes
16094fee23f9Smrg    pointers and iterators, and that must be fixed before safer iterators
16104fee23f9Smrg    can be introduced.
16114fee23f9Smrg
16124fee23f9Smrg    Some of the functions in &lt;cstring&gt; are different from the C version.
16134fee23f9Smrg    generally overloaded on const and non-const argument pointers. For
16144fee23f9Smrg    example, in &lt;cstring&gt; strchr is overloaded. The functions isupper
16154fee23f9Smrg    etc. in &lt;cctype&gt; typically implemented as macros in C are functions
16164fee23f9Smrg    in C++, because they are overloaded with others of the same name
16174fee23f9Smrg    defined in &lt;locale&gt;.
16184fee23f9Smrg
16194fee23f9Smrg    Many of the functions required in &lt;cwctype&gt; and &lt;cwchar&gt; cannot be
16204fee23f9Smrg    implemented using underlying C facilities on intended targets because
16214fee23f9Smrg    such facilities only partly exist.
16224fee23f9Smrg
16234fee23f9Smrg    Chapter 22  Locale
16244fee23f9Smrg    ------------------
16254fee23f9Smrg    Headers: &lt;locale&gt;
16264fee23f9Smrg    C headers: &lt;clocale&gt;
16274fee23f9Smrg
16284fee23f9Smrg    We have a "mostly complete" class locale, with the exception of
16294fee23f9Smrg    code for constructing, and handling the names of, named locales.
16304fee23f9Smrg    The ways that locales are named (particularly when categories
16314fee23f9Smrg    (e.g. LC_TIME, LC_COLLATE) are different) varies among all target
16324fee23f9Smrg    environments. This code must be written in various versions and
16334fee23f9Smrg    chosen by configuration parameters.
16344fee23f9Smrg
16354fee23f9Smrg    Members of many of the facets defined in &lt;locale&gt; are stubs. Generally,
16364fee23f9Smrg    there are two sets of facets: the base class facets (which are supposed
16374fee23f9Smrg    to implement the "C" locale) and the "byname" facets, which are supposed
16384fee23f9Smrg    to read files to determine their behavior. The base ctype&lt;&gt;, collate&lt;&gt;,
16394fee23f9Smrg    and numpunct&lt;&gt; facets are "mostly complete", except that the table of
16404fee23f9Smrg    bitmask values used for "is" operations, and corresponding mask values,
16414fee23f9Smrg    are still defined in libio and just included/linked. (We will need to
16424fee23f9Smrg    implement these tables independently, soon, but should take advantage
16434fee23f9Smrg    of libio where possible.)  The num_put&lt;&gt;::put members for integer types
16444fee23f9Smrg    are "mostly complete".
16454fee23f9Smrg
16464fee23f9Smrg    A complete list of what has and has not been implemented may be
16474fee23f9Smrg    found in CHECKLIST. However, note that the current definition of
16484fee23f9Smrg    codecvt&lt;wchar_t,char,mbstate_t&gt; is wrong. It should simply write
16494fee23f9Smrg    out the raw bytes representing the wide characters, rather than
16504fee23f9Smrg    trying to convert each to a corresponding single "char" value.
16514fee23f9Smrg
16524fee23f9Smrg    Some of the facets are more important than others. Specifically,
16534fee23f9Smrg    the members of ctype&lt;&gt;, numpunct&lt;&gt;, num_put&lt;&gt;, and num_get&lt;&gt; facets
16544fee23f9Smrg    are used by other library facilities defined in &lt;string&gt;, &lt;istream&gt;,
16554fee23f9Smrg    and &lt;ostream&gt;, and the codecvt&lt;&gt; facet is used by basic_filebuf&lt;&gt;
16564fee23f9Smrg    in &lt;fstream&gt;, so a conforming iostream implementation depends on
16574fee23f9Smrg    these.
16584fee23f9Smrg
16594fee23f9Smrg    The "long long" type eventually must be supported, but code mentioning
16604fee23f9Smrg    it should be wrapped in #if guards to allow pedantic-mode compiling.
16614fee23f9Smrg
16624fee23f9Smrg    Performance of num_put&lt;&gt; and num_get&lt;&gt; depend critically on
16634fee23f9Smrg    caching computed values in ios_base objects, and on extensions
16644fee23f9Smrg    to the interface with streambufs.
16654fee23f9Smrg
16664fee23f9Smrg    Specifically: retrieving a copy of the locale object, extracting
16674fee23f9Smrg    the needed facets, and gathering data from them, for each call to
16684fee23f9Smrg    (e.g.) operator&lt;&lt; would be prohibitively slow.  To cache format
16694fee23f9Smrg    data for use by num_put&lt;&gt; and num_get&lt;&gt; we have a _Format_cache&lt;&gt;
16704fee23f9Smrg    object stored in the ios_base::pword() array. This is constructed
16714fee23f9Smrg    and initialized lazily, and is organized purely for utility. It
16724fee23f9Smrg    is discarded when a new locale with different facets is imbued.
16734fee23f9Smrg
16744fee23f9Smrg    Using only the public interfaces of the iterator arguments to the
16754fee23f9Smrg    facet functions would limit performance by forbidding "vector-style"
16764fee23f9Smrg    character operations. The streambuf iterator optimizations are
16774fee23f9Smrg    described under chapter 24, but facets can also bypass the streambuf
16784fee23f9Smrg    iterators via explicit specializations and operate directly on the
16794fee23f9Smrg    streambufs, and use extended interfaces to get direct access to the
16804fee23f9Smrg    streambuf internal buffer arrays. These extensions are mentioned
16814fee23f9Smrg    under chapter 27. These optimizations are particularly important
16824fee23f9Smrg    for input parsing.
16834fee23f9Smrg
16844fee23f9Smrg    Unused virtual members of locale facets can be omitted, as mentioned
16854fee23f9Smrg    above, by a smart linker.
16864fee23f9Smrg
16874fee23f9Smrg    Chapter 23  Containers
16884fee23f9Smrg    ----------------------
16894fee23f9Smrg    Headers: &lt;deque&gt; &lt;list&gt; &lt;queue&gt; &lt;stack&gt; &lt;vector&gt; &lt;map&gt; &lt;set&gt; &lt;bitset&gt;
16904fee23f9Smrg
16914fee23f9Smrg    All the components in chapter 23 are implemented in the SGI STL.
16924fee23f9Smrg    They are "mostly complete"; they include a large number of
16934fee23f9Smrg    nonconforming extensions which must be wrapped. Some of these
16944fee23f9Smrg    are used internally and must be renamed or duplicated.
16954fee23f9Smrg
16964fee23f9Smrg    The SGI components are optimized for large-memory environments. For
16974fee23f9Smrg    embedded targets, different criteria might be more appropriate. Users
16984fee23f9Smrg    will want to be able to tune this behavior. We should provide
16994fee23f9Smrg    ways for users to compile the library with different memory usage
17004fee23f9Smrg    characteristics.
17014fee23f9Smrg
17024fee23f9Smrg    A lot more work is needed on factoring out common code from different
17034fee23f9Smrg    specializations to reduce code size here and in chapter 25. The
17044fee23f9Smrg    easiest fix for this would be a compiler/ABI improvement that allows
17054fee23f9Smrg    the compiler to recognize when a specialization depends only on the
17064fee23f9Smrg    size (or other gross quality) of a template argument, and allow the
17074fee23f9Smrg    linker to share the code with similar specializations. In its
17084fee23f9Smrg    absence, many of the algorithms and containers can be partial-
17094fee23f9Smrg    specialized, at least for the case of pointers, but this only solves
17104fee23f9Smrg    a small part of the problem. Use of a type_traits-style template
17114fee23f9Smrg    allows a few more optimization opportunities, more if the compiler
17124fee23f9Smrg    can generate the specializations automatically.
17134fee23f9Smrg
17144fee23f9Smrg    As an optimization, containers can specialize on the default allocator
17154fee23f9Smrg    and bypass it, or take advantage of details of its implementation
17164fee23f9Smrg    after it has been improved upon.
17174fee23f9Smrg
17184fee23f9Smrg    Replacing the vector iterators, which currently are simple element
17194fee23f9Smrg    pointers, with class objects would greatly increase the safety of the
17204fee23f9Smrg    client interface, and also permit a "debug" mode in which range,
17214fee23f9Smrg    ownership, and validity are rigorously checked. The current use of
17224fee23f9Smrg    pointers for iterators is evil.
17234fee23f9Smrg
17244fee23f9Smrg    As mentioned for chapter 24, the deque iterator is a good example of
17254fee23f9Smrg    an opportunity to implement a "staged" iterator that would benefit
17264fee23f9Smrg    from specializations of some algorithms.
17274fee23f9Smrg
17284fee23f9Smrg    Chapter 24  Iterators
17294fee23f9Smrg    ---------------------
17304fee23f9Smrg    Headers: &lt;iterator&gt;
17314fee23f9Smrg
17324fee23f9Smrg    Standard iterators are "mostly complete", with the exception of
17334fee23f9Smrg    the stream iterators, which are not yet templatized on the
17344fee23f9Smrg    stream type. Also, the base class template iterator&lt;&gt; appears
17354fee23f9Smrg    to be wrong, so everything derived from it must also be wrong,
17364fee23f9Smrg    currently.
17374fee23f9Smrg
17384fee23f9Smrg    The streambuf iterators (currently located in stl/bits/std_iterator.h,
17394fee23f9Smrg    but should be under bits/) can be rewritten to take advantage of
17404fee23f9Smrg    friendship with the streambuf implementation.
17414fee23f9Smrg
17424fee23f9Smrg    Matt Austern has identified opportunities where certain iterator
17434fee23f9Smrg    types, particularly including streambuf iterators and deque
17444fee23f9Smrg    iterators, have a "two-stage" quality, such that an intermediate
17454fee23f9Smrg    limit can be checked much more quickly than the true limit on
17464fee23f9Smrg    range operations. If identified with a member of iterator_traits,
17474fee23f9Smrg    algorithms may be specialized for this case. Of course the
17484fee23f9Smrg    iterators that have this quality can be identified by specializing
17494fee23f9Smrg    a traits class.
17504fee23f9Smrg
17514fee23f9Smrg    Many of the algorithms must be specialized for the streambuf
17524fee23f9Smrg    iterators, to take advantage of block-mode operations, in order
17534fee23f9Smrg    to allow iostream/locale operations' performance not to suffer.
17544fee23f9Smrg    It may be that they could be treated as staged iterators and
17554fee23f9Smrg    take advantage of those optimizations.
17564fee23f9Smrg
17574fee23f9Smrg    Chapter 25  Algorithms
17584fee23f9Smrg    ----------------------
17594fee23f9Smrg    Headers: &lt;algorithm&gt;
17604fee23f9Smrg    C headers: &lt;cstdlib&gt; (also in 18, 21, 26))
17614fee23f9Smrg
17624fee23f9Smrg    The algorithms are "mostly complete". As mentioned above, they
17634fee23f9Smrg    are optimized for speed at the expense of code and data size.
17644fee23f9Smrg
17654fee23f9Smrg    Specializations of many of the algorithms for non-STL types would
17664fee23f9Smrg    give performance improvements, but we must use great care not to
17674fee23f9Smrg    interfere with fragile template overloading semantics for the
17684fee23f9Smrg    standard interfaces. Conventionally the standard function template
17694fee23f9Smrg    interface is an inline which delegates to a non-standard function
17704fee23f9Smrg    which is then overloaded (this is already done in many places in
17714fee23f9Smrg    the library). Particularly appealing opportunities for the sake of
17724fee23f9Smrg    iostream performance are for copy and find applied to streambuf
17734fee23f9Smrg    iterators or (as noted elsewhere) for staged iterators, of which
17744fee23f9Smrg    the streambuf iterators are a good example.
17754fee23f9Smrg
17764fee23f9Smrg    The bsearch and qsort functions cannot be overloaded properly as
17774fee23f9Smrg    required by the standard because gcc does not yet allow overloading
17784fee23f9Smrg    on the extern-"C"-ness of a function pointer.
17794fee23f9Smrg
17804fee23f9Smrg    Chapter 26  Numerics
17814fee23f9Smrg    --------------------
17824fee23f9Smrg    Headers: &lt;complex&gt; &lt;valarray&gt; &lt;numeric&gt;
17834fee23f9Smrg    C headers: &lt;cmath&gt;, &lt;cstdlib&gt; (also 18, 21, 25)
17844fee23f9Smrg
17854fee23f9Smrg    Numeric components: Gabriel dos Reis's valarray, Drepper's complex,
17864fee23f9Smrg    and the few algorithms from the STL are "mostly done".  Of course
17874fee23f9Smrg    optimization opportunities abound for the numerically literate. It
17884fee23f9Smrg    is not clear whether the valarray implementation really conforms
17894fee23f9Smrg    fully, in the assumptions it makes about aliasing (and lack thereof)
17904fee23f9Smrg    in its arguments.
17914fee23f9Smrg
17924fee23f9Smrg    The C div() and ldiv() functions are interesting, because they are the
17934fee23f9Smrg    only case where a C library function returns a class object by value.
17944fee23f9Smrg    Since the C++ type div_t must be different from the underlying C type
17954fee23f9Smrg    (which is in the wrong namespace) the underlying functions div() and
17964fee23f9Smrg    ldiv() cannot be re-used efficiently. Fortunately they are trivial to
17974fee23f9Smrg    re-implement.
17984fee23f9Smrg
17994fee23f9Smrg    Chapter 27  Iostreams
18004fee23f9Smrg    ---------------------
18014fee23f9Smrg    Headers: &lt;iosfwd&gt; &lt;streambuf&gt; &lt;ios&gt; &lt;ostream&gt; &lt;istream&gt; &lt;iostream&gt;
18024fee23f9Smrg    &lt;iomanip&gt; &lt;sstream&gt; &lt;fstream&gt;
18034fee23f9Smrg    C headers: &lt;cstdio&gt; &lt;cwchar&gt; (also in 21)
18044fee23f9Smrg
18054fee23f9Smrg    Iostream is currently in a very incomplete state. &lt;iosfwd&gt;, &lt;iomanip&gt;,
18064fee23f9Smrg    ios_base, and basic_ios&lt;&gt; are "mostly complete". basic_streambuf&lt;&gt; and
18074fee23f9Smrg    basic_ostream&lt;&gt; are well along, but basic_istream&lt;&gt; has had little work
18084fee23f9Smrg    done. The standard stream objects, &lt;sstream&gt; and &lt;fstream&gt; have been
18094fee23f9Smrg    started; basic_filebuf&lt;&gt; "write" functions have been implemented just
18104fee23f9Smrg    enough to do "hello, world".
18114fee23f9Smrg
18124fee23f9Smrg    Most of the istream and ostream operators &lt;&lt; and &gt;&gt; (with the exception
18134fee23f9Smrg    of the op&lt;&lt;(integer) ones) have not been changed to use locale primitives,
18144fee23f9Smrg    sentry objects, or char_traits members.
18154fee23f9Smrg
18164fee23f9Smrg    All these templates should be manually instantiated for char and
18174fee23f9Smrg    wchar_t in a way that links only used members into user programs.
18184fee23f9Smrg
18194fee23f9Smrg    Streambuf is fertile ground for optimization extensions. An extended
18204fee23f9Smrg    interface giving iterator access to its internal buffer would be very
18214fee23f9Smrg    useful for other library components.
18224fee23f9Smrg
18234fee23f9Smrg    Iostream operations (primarily operators &lt;&lt; and &gt;&gt;) can take advantage
18244fee23f9Smrg    of the case where user code has not specified a locale, and bypass locale
18254fee23f9Smrg    operations entirely. The current implementation of op&lt;&lt;/num_put&lt;&gt;::put,
18264fee23f9Smrg    for the integer types, demonstrates how they can cache encoding details
18274fee23f9Smrg    from the locale on each operation. There is lots more room for
18284fee23f9Smrg    optimization in this area.
18294fee23f9Smrg
18304fee23f9Smrg    The definition of the relationship between the standard streams
18314fee23f9Smrg    cout et al. and stdout et al. requires something like a "stdiobuf".
18324fee23f9Smrg    The SGI solution of using double-indirection to actually use a
18334fee23f9Smrg    stdio FILE object for buffering is unsatisfactory, because it
18344fee23f9Smrg    interferes with peephole loop optimizations.
18354fee23f9Smrg
18364fee23f9Smrg    The &lt;sstream&gt; header work has begun. stringbuf can benefit from
18374fee23f9Smrg    friendship with basic_string&lt;&gt; and basic_string&lt;&gt;::_Rep to use
18384fee23f9Smrg    those objects directly as buffers, and avoid allocating and making
18394fee23f9Smrg    copies.
18404fee23f9Smrg
18414fee23f9Smrg    The basic_filebuf&lt;&gt; template is a complex beast. It is specified to
18424fee23f9Smrg    use the locale facet codecvt&lt;&gt; to translate characters between native
18434fee23f9Smrg    files and the locale character encoding. In general this involves
18444fee23f9Smrg    two buffers, one of "char" representing the file and another of
18454fee23f9Smrg    "char_type", for the stream, with codecvt&lt;&gt; translating. The process
18464fee23f9Smrg    is complicated by the variable-length nature of the translation, and
18474fee23f9Smrg    the need to seek to corresponding places in the two representations.
18484fee23f9Smrg    For the case of basic_filebuf&lt;char&gt;, when no translation is needed,
18494fee23f9Smrg    a single buffer suffices. A specialized filebuf can be used to reduce
18504fee23f9Smrg    code space overhead when no locale has been imbued. Matt Austern's
18514fee23f9Smrg    work at SGI will be useful, perhaps directly as a source of code, or
18524fee23f9Smrg    at least as an example to draw on.
18534fee23f9Smrg
18544fee23f9Smrg    Filebuf, almost uniquely (cf. operator new), depends heavily on
18554fee23f9Smrg    underlying environmental facilities. In current releases iostream
18564fee23f9Smrg    depends fairly heavily on libio constant definitions, but it should
18574fee23f9Smrg    be made independent.  It also depends on operating system primitives
18584fee23f9Smrg    for file operations. There is immense room for optimizations using
18594fee23f9Smrg    (e.g.) mmap for reading. The shadow/ directory wraps, besides the
18604fee23f9Smrg    standard C headers, the libio.h and unistd.h headers, for use mainly
18614fee23f9Smrg    by filebuf. These wrappings have not been completed, though there
18624fee23f9Smrg    is scaffolding in place.
18634fee23f9Smrg
18644fee23f9Smrg    The encapsulation of certain C header &lt;cstdio&gt; names presents an
18654fee23f9Smrg    interesting problem. It is possible to define an inline std::fprintf()
18664fee23f9Smrg    implemented in terms of the 'extern "C"' vfprintf(), but there is no
18674fee23f9Smrg    standard vfscanf() to use to implement std::fscanf(). It appears that
18684fee23f9Smrg    vfscanf but be re-implemented in C++ for targets where no vfscanf
18694fee23f9Smrg    extension has been defined. This is interesting in that it seems
18704fee23f9Smrg    to be the only significant case in the C library where this kind of
18714fee23f9Smrg    rewriting is necessary. (Of course Glibc provides the vfscanf()
18724fee23f9Smrg    extension.)  (The functions related to exit() must be rewritten
18734fee23f9Smrg    for other reasons.)
18744fee23f9Smrg
18754fee23f9Smrg
18764fee23f9Smrg    Annex D
18774fee23f9Smrg    -------
18784fee23f9Smrg    Headers: &lt;strstream&gt;
18794fee23f9Smrg
18804fee23f9Smrg    Annex D defines many non-library features, and many minor
18814fee23f9Smrg    modifications to various headers, and a complete header.
18824fee23f9Smrg    It is "mostly done", except that the libstdc++-2 &lt;strstream&gt;
18834fee23f9Smrg    header has not been adopted into the library, or checked to
18844fee23f9Smrg    verify that it matches the draft in those details that were
18854fee23f9Smrg    clarified by the committee. Certainly it must at least be
18864fee23f9Smrg    moved into the std namespace.
18874fee23f9Smrg
18884fee23f9Smrg    We still need to wrap all the deprecated features in #if guards
18894fee23f9Smrg    so that pedantic compile modes can detect their use.
18904fee23f9Smrg
18914fee23f9Smrg    Nonstandard Extensions
18924fee23f9Smrg    ----------------------
18934fee23f9Smrg    Headers: &lt;iostream.h&gt; &lt;strstream.h&gt; &lt;hash&gt; &lt;rbtree&gt;
18944fee23f9Smrg    &lt;pthread_alloc&gt; &lt;stdiobuf&gt; (etc.)
18954fee23f9Smrg
18964fee23f9Smrg    User code has come to depend on a variety of nonstandard components
18974fee23f9Smrg    that we must not omit. Much of this code can be adopted from
18984fee23f9Smrg    libstdc++-v2 or from the SGI STL. This particularly includes
18994fee23f9Smrg    &lt;iostream.h&gt;, &lt;strstream.h&gt;, and various SGI extensions such
19004fee23f9Smrg    as &lt;hash_map.h&gt;. Many of these are already placed in the
19014fee23f9Smrg    subdirectories ext/ and backward/. (Note that it is better to
19024fee23f9Smrg    include them via "&lt;backward/hash_map.h&gt;" or "&lt;ext/hash_map&gt;" than
19034fee23f9Smrg    to search the subdirectory itself via a "-I" directive.
19044fee23f9Smrg  </literallayout>
190548fb7bfaSmrg</section>
19064fee23f9Smrg
19074fee23f9Smrg</appendix>
1908