OSDN Git Service

033bd7dbbef5cc0769c63fc00be8b02c2fdf4a20
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / doc / xml / manual / appendix_contributing.xml
1 <?xml version='1.0'?>
2 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
3  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 
4 [ ]>
5
6 <appendix id="appendix.contrib" xreflabel="Contributing">
7 <?dbhtml filename="appendix_contributing.html"?>
8  
9 <appendixinfo>
10   <keywordset>
11     <keyword>
12       ISO C++
13     </keyword>
14     <keyword>
15       library
16     </keyword>
17   </keywordset>
18 </appendixinfo>
19
20 <title>Contributing</title>
21
22 <para> 
23   The GNU C++ Library follows an open development model. Active
24   contributors are assigned maintainer-ship responsibility, and given
25   write access to the source repository. First time contributors
26   should follow this procedure:
27 </para>
28
29 <sect1 id="contrib.list" xreflabel="Contributor Checklist">
30   <title>Contributor Checklist</title>
31
32   <sect2 id="list.reading" xreflabel="list.reading">
33     <title>Reading</title>
34
35 <itemizedlist>
36  <listitem><para> Get and read the relevant sections of the C++ language
37 specification. Copies of the full ISO 14882 standard are available on
38 line via the ISO mirror site for committee members. Non-members, or
39 those who have not paid for the privilege of sitting on the committee
40 and sustained their two meeting commitment for voting rights, may get
41 a copy of the standard from their respective national standards
42 organization. In the USA, this national standards organization is ANSI
43 and their web-site is right
44
45  <ulink url="http://www.ansi.org">here.</ulink> 
46 (And if you've already registered with them, clicking this link will take you to directly to the place where you can 
47 <ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink>
48 </para></listitem>
49
50 <listitem><para> The library working group bugs, and known defects, can be obtained here:
51  <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink>
52 </para></listitem>
53
54 <listitem><para> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html"> here </ulink>.
55 </para></listitem>
56
57  <listitem><para> Peruse the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU Coding Standards</ulink>, and chuckle when you hit the part about "Using Languages Other Than C." 
58 </para></listitem>
59
60  <listitem><para> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <ulink url="C++STYLE"> here. </ulink>
61 </para></listitem>
62
63  <listitem><para> And last but certainly not least, read the library-specific information found <ulink url="../documentation.html"> here.</ulink>
64 </para></listitem>
65
66 </itemizedlist>
67
68     </sect2>
69     <sect2 id="list.copyright" xreflabel="list.copyright">
70       <title>Assignment</title>
71 <para>
72 Small changes can be accepted without a copyright assignment form on
73 file. New code and additions to the library need completed copyright
74 assignment form on file at the FSF. Note: your employer may be required
75 to fill out appropriate disclaimer forms as well. 
76 </para>
77
78 <para> 
79   Historically, the libstdc++ assignment form added the following
80   question:
81 </para>
82
83 <para>
84   <quote>
85   Which Belgian comic book character is better, Tintin or Asterix, and
86   why?
87   </quote>
88 </para>
89
90 <para>
91 While not strictly necessary, humoring the maintainers and answering
92 this question would be appreciated.
93 </para>
94
95 <para>
96 For more information about getting a copyright assignment, please see 
97 <ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal
98 Matters</ulink>.
99 </para>
100
101 <para>
102 Please contact Benjamin Kosnik at
103 <email>bkoz+assign@redhat.com</email> if you are confused
104 about the assignment or have general licensing questions. When
105 requesting an assignment form from
106 <email>mailto:assign@gnu.org</email>, please cc the libstdc++
107 maintainer above so that progress can be monitored.
108 </para>
109     </sect2>
110
111     <sect2 id="list.getting" xreflabel="list.getting">
112       <title>Getting Sources</title>
113       <para>
114         <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access
115         (look for &quot;Write after approval&quot;)</ulink>
116       </para>
117     </sect2>
118
119     <sect2 id="list.patches" xreflabel="list.patches">
120       <title>Submitting Patches</title>
121
122
123 <para>
124 Every patch must have several pieces of information before it can be
125 properly evaluated. Ideally (and to ensure the fastest possible
126 response from the maintainers) it would have all of these pieces:
127 </para>
128
129 <itemizedlist>
130
131  <listitem><para> A description of the bug and how your patch fixes this bug. For
132  new features a description of the feature and your implementation. </para></listitem>
133
134  <listitem><para> A ChangeLog entry as plain text; see the various ChangeLog files
135  for format and content. If using you are using emacs as your editor,
136  simply position the insertion point at the beginning of your change
137  and hit CX-4a to bring up the appropriate ChangeLog
138  entry. See--magic! Similar functionality also exists for vi.  </para></listitem>
139
140  <listitem><para> A testsuite submission or sample program that will easily and
141  simply show the existing error or test new functionality.  </para></listitem>
142
143  <listitem><para> The patch itself. If you are accessing the SVN repository
144  use "svn update; svn diff NEW"; else, use "diff -cp OLD NEW"
145  ... If your version of diff does not support these options, then
146  get the latest version of GNU diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN Tricks</ulink> wiki page
147  has information on customising the output of <code>svn diff</code>.</para></listitem>
148
149  <listitem><para> When you have all these pieces, bundle them up in a mail message
150 and send it to libstdc++@gcc.gnu.org. All patches and related
151 discussion should be sent to the libstdc++ mailing list. </para></listitem>
152
153 </itemizedlist>
154
155     </sect2>
156
157   </sect1>
158
159   <sect1 id="contrib.coding_style" xreflabel="Coding Style">
160     <title>Coding Style</title>
161     <para>
162     </para>
163     <sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad">
164       <title>Bad Itentifiers</title>
165 <para>
166 Identifiers that conflict and should be avoided.
167 </para>
168
169 <literallayout>
170
171 This is the list of names "reserved to the implementation" that
172 have been claimed by certain compilers and system headers of interest,
173 and should not be used in the library.  It will grow, of course.
174 We generally are interested in names that are not all-caps, except
175 for those like "_T"
176
177 For Solarix:
178 _B
179 _C
180 _L
181 _N
182 _P
183 _S
184 _U
185 _X
186 _E1
187 ..
188 _E24
189
190 Irix adds:
191 _A
192 _G
193
194 MS adds:
195 _T
196
197 BSD adds:
198 __used
199 __unused
200 __inline
201 _Complex
202 __istype
203 __maskrune
204 __tolower
205 __toupper
206 __wchar_t
207 __wint_t
208 _res
209 _res_ext
210 __tg_*
211
212 For GCC:
213
214   [Note that this list is out of date.  It applies to the old
215   name-mangling; in G++ 3.0 and higher a different name-mangling is
216   used.  In addition, many of the bugs relating to G++ interpreting
217   these names as operators have been fixed.]
218
219   The full set of __* identifiers (combined from gcc/cp/lex.c and
220   gcc/cplus-dem.c) that are either old or new, but are definitely 
221   recognized by the demangler, is:
222
223 __aa
224 __aad
225 __ad
226 __addr
227 __adv
228 __aer
229 __als
230 __alshift
231 __amd
232 __ami
233 __aml
234 __amu
235 __aor
236 __apl
237 __array
238 __ars
239 __arshift
240 __as
241 __bit_and
242 __bit_ior
243 __bit_not
244 __bit_xor
245 __call
246 __cl
247 __cm
248 __cn
249 __co
250 __component
251 __compound
252 __cond
253 __convert
254 __delete
255 __dl
256 __dv
257 __eq
258 __er
259 __ge
260 __gt
261 __indirect
262 __le
263 __ls
264 __lt
265 __max
266 __md
267 __method_call
268 __mi
269 __min
270 __minus
271 __ml
272 __mm
273 __mn
274 __mult
275 __mx
276 __ne
277 __negate
278 __new
279 __nop
280 __nt
281 __nw
282 __oo
283 __op
284 __or
285 __pl
286 __plus
287 __postdecrement
288 __postincrement
289 __pp
290 __pt
291 __rf
292 __rm
293 __rs
294 __sz
295 __trunc_div
296 __trunc_mod
297 __truth_andif
298 __truth_not
299 __truth_orif
300 __vc
301 __vd
302 __vn
303
304 SGI badnames:
305 __builtin_alloca
306 __builtin_fsqrt
307 __builtin_sqrt
308 __builtin_fabs
309 __builtin_dabs
310 __builtin_cast_f2i
311 __builtin_cast_i2f
312 __builtin_cast_d2ll
313 __builtin_cast_ll2d
314 __builtin_copy_dhi2i
315 __builtin_copy_i2dhi
316 __builtin_copy_dlo2i
317 __builtin_copy_i2dlo
318 __add_and_fetch
319 __sub_and_fetch
320 __or_and_fetch
321 __xor_and_fetch
322 __and_and_fetch
323 __nand_and_fetch
324 __mpy_and_fetch
325 __min_and_fetch
326 __max_and_fetch
327 __fetch_and_add
328 __fetch_and_sub
329 __fetch_and_or
330 __fetch_and_xor
331 __fetch_and_and
332 __fetch_and_nand
333 __fetch_and_mpy
334 __fetch_and_min
335 __fetch_and_max
336 __lock_test_and_set
337 __lock_release
338 __lock_acquire
339 __compare_and_swap
340 __synchronize
341 __high_multiply
342 __unix
343 __sgi
344 __linux__
345 __i386__
346 __i486__
347 __cplusplus
348 __embedded_cplusplus
349 // long double conversion members mangled as __opr
350 // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html
351 _opr
352 </literallayout>
353     </sect2>
354
355     <sect2 id="coding_style.example" xreflabel="coding_style.example">
356       <title>By Example</title>
357 <literallayout>
358
359 This library is written to appropriate C++ coding standards.  As such,
360 it is intended to precede the recommendations of the GNU Coding
361 Standard, which can be referenced in full here:
362
363 http://www.gnu.org/prep/standards/standards.html#Formatting
364
365 The rest of this is also interesting reading, but skip the "Design
366 Advice" part.
367
368 The GCC coding conventions are here, and are also useful:
369 http://gcc.gnu.org/codingconventions.html
370
371 In addition, because it doesn't seem to be stated explicitly anywhere
372 else, there is an 80 column source limit.
373
374 ChangeLog entries for member functions should use the
375 classname::member function name syntax as follows:
376
377 1999-04-15  Dennis Ritchie  &lt;dr@att.com&gt;
378
379         * src/basic_file.cc (__basic_file::open): Fix thinko in
380         _G_HAVE_IO_FILE_OPEN bits.
381
382 Notable areas of divergence from what may be previous local practice
383 (particularly for GNU C) include:
384
385 01. Pointers and references
386   char* p = "flop";
387   char&amp; c = *p;
388      -NOT-
389   char *p = "flop";  // wrong
390   char &amp;c = *p;      // wrong
391   
392     Reason: In C++, definitions are mixed with executable code.  Here,       
393             p is being initialized, not *p.  This is near-universal
394             practice among C++ programmers; it is normal for C hackers
395             to switch spontaneously as they gain experience.
396
397 02. Operator names and parentheses
398   operator==(type)
399      -NOT-
400   operator == (type)  // wrong
401      
402     Reason: The == is part of the function name.  Separating
403             it makes the declaration look like an expression. 
404
405 03. Function names and parentheses
406   void mangle()
407      -NOT-
408   void mangle ()  // wrong
409
410      Reason: no space before parentheses (except after a control-flow
411      keyword) is near-universal practice for C++.  It identifies the
412      parentheses as the function-call operator or declarator, as 
413      opposed to an expression or other overloaded use of parentheses.
414
415 04. Template function indentation
416   template&lt;typename T&gt;
417     void 
418     template_function(args)
419     { }
420       -NOT-
421   template&lt;class T&gt;
422   void template_function(args) {};
423   
424      Reason: In class definitions, without indentation whitespace is
425              needed both above and below the declaration to distinguish
426              it visually from other members.  (Also, re: "typename"
427              rather than "class".)  T often could be int, which is 
428              not a class.  ("class", here, is an anachronism.)
429
430 05. Template class indentation
431   template&lt;typename _CharT, typename _Traits&gt;
432     class basic_ios : public ios_base
433     {
434     public:
435       // Types:
436     };
437   -NOT-
438   template&lt;class _CharT, class _Traits&gt;
439   class basic_ios : public ios_base
440     {
441     public:
442       // Types:
443     };
444   -NOT-
445   template&lt;class _CharT, class _Traits&gt;
446     class basic_ios : public ios_base
447   {
448     public:
449       // Types:
450   };
451
452 06. Enumerators
453   enum
454   {
455     space = _ISspace,
456     print = _ISprint,
457     cntrl = _IScntrl
458   };
459   -NOT-
460   enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
461
462 07. Member initialization lists
463    All one line, separate from class name.
464
465   gribble::gribble() 
466   : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
467   { }
468   -NOT-
469   gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
470   { }
471
472 08. Try/Catch blocks
473   try 
474     {
475       //
476     }   
477   catch (...)
478     {
479       //
480     }   
481   -NOT-
482   try {
483     // 
484   } catch(...) { 
485     //
486   }
487
488 09. Member functions declarations and definitions
489    Keywords such as extern, static, export, explicit, inline, etc
490    go on the line above the function name. Thus
491
492   virtual int   
493   foo()
494   -NOT-
495   virtual int foo()
496
497         Reason: GNU coding conventions dictate return types for functions
498         are on a separate line than the function name and parameter list
499         for definitions. For C++, where we have member functions that can
500         be either inline definitions or declarations, keeping to this
501         standard allows all member function names for a given class to be
502         aligned to the same margin, increasing readibility.
503
504
505 10. Invocation of member functions with "this-&gt;"
506    For non-uglified names, use this-&gt;name to call the function.
507
508   this-&gt;sync()
509   -NOT-
510   sync()
511
512         Reason: Koenig lookup.
513
514 11. Namespaces
515   namespace std
516   {
517     blah blah blah;
518   } // namespace std
519
520   -NOT-
521
522   namespace std {
523     blah blah blah;
524   } // namespace std
525
526 12. Spacing under protected and private in class declarations:
527    space above, none below
528    ie
529
530    public:
531      int foo;
532
533    -NOT-
534    public:
535    
536      int foo;
537
538 13. Spacing WRT return statements.
539    no extra spacing before returns, no parenthesis
540    ie
541
542    }
543    return __ret;
544
545    -NOT-
546    }
547
548    return __ret;
549
550    -NOT-
551
552    }
553    return (__ret);
554
555
556 14. Location of global variables.
557    All global variables of class type, whether in the "user visable"
558    space (e.g., cin) or the implementation namespace, must be defined
559    as a character array with the appropriate alignment and then later
560    re-initialized to the correct value.
561
562    This is due to startup issues on certain platforms, such as AIX.
563    For more explanation and examples, see src/globals.cc.  All such
564    variables should be contained in that file, for simplicity.
565
566 15. Exception abstractions
567     Use the exception abstractions found in functexcept.h, which allow
568     C++ programmers to use this library with -fno-exceptions. (Even if
569     that is rarely advisable, it's a necessary evil for backwards
570     compatibility.)
571
572 16. Exception error messages
573     All start with the name of the function where the exception is
574     thrown, and then (optional) descriptive text is added. Example:
575
576     __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
577
578     Reason: The verbose terminate handler prints out exception::what(),
579     as well as the typeinfo for the thrown exception. As this is the
580     default terminate handler, by putting location info into the
581     exception string, a very useful error message is printed out for
582     uncaught exceptions. So useful, in fact, that non-programmers can
583     give useful error messages, and programmers can intelligently
584     speculate what went wrong without even using a debugger.
585
586 17. The doxygen style guide to comments is a separate document,
587     see index.
588
589 The library currently has a mixture of GNU-C and modern C++ coding
590 styles.  The GNU C usages will be combed out gradually.
591
592 Name patterns:
593
594 For nonstandard names appearing in Standard headers, we are constrained 
595 to use names that begin with underscores.  This is called "uglification".
596 The convention is:
597
598   Local and argument names:  __[a-z].*
599
600     Examples:  __count  __ix  __s1  
601
602   Type names and template formal-argument names: _[A-Z][^_].*
603
604     Examples:  _Helper  _CharT  _N 
605
606   Member data and function names: _M_.*
607
608     Examples:  _M_num_elements  _M_initialize ()
609
610   Static data members, constants, and enumerations: _S_.*
611
612     Examples: _S_max_elements  _S_default_value
613
614 Don't use names in the same scope that differ only in the prefix, 
615 e.g. _S_top and _M_top.  See BADNAMES for a list of forbidden names.
616 (The most tempting of these seem to be and "_T" and "__sz".)
617
618 Names must never have "__" internally; it would confuse name
619 unmanglers on some targets.  Also, never use "__[0-9]", same reason.
620
621 --------------------------
622
623 [BY EXAMPLE]
624     
625 #ifndef  _HEADER_
626 #define  _HEADER_ 1
627
628 namespace std
629 {
630   class gribble
631   {
632   public:
633     gribble() throw();
634
635     gribble(const gribble&amp;);
636
637     explicit 
638     gribble(int __howmany);
639
640     gribble&amp; 
641     operator=(const gribble&amp;);
642
643     virtual 
644     ~gribble() throw ();
645
646     // Start with a capital letter, end with a period.
647     inline void  
648     public_member(const char* __arg) const;
649
650     // In-class function definitions should be restricted to one-liners.
651     int 
652     one_line() { return 0 }
653
654     int 
655     two_lines(const char* arg) 
656     { return strchr(arg, 'a'); }
657
658     inline int 
659     three_lines();  // inline, but defined below.
660
661     // Note indentation.
662     template&lt;typename _Formal_argument&gt;
663       void 
664       public_template() const throw();
665
666     template&lt;typename _Iterator&gt;
667       void 
668       other_template();
669
670   private:
671     class _Helper;
672
673     int _M_private_data;
674     int _M_more_stuff;
675     _Helper* _M_helper;
676     int _M_private_function();
677
678     enum _Enum 
679       { 
680         _S_one, 
681         _S_two 
682       };
683
684     static void 
685     _S_initialize_library();
686   };
687
688 // More-or-less-standard language features described by lack, not presence.
689 # ifndef _G_NO_LONGLONG
690   extern long long _G_global_with_a_good_long_name;  // avoid globals!
691 # endif
692
693   // Avoid in-class inline definitions, define separately;
694   // likewise for member class definitions:
695   inline int
696   gribble::public_member() const
697   { int __local = 0; return __local; }
698
699   class gribble::_Helper
700   {
701     int _M_stuff;
702
703     friend class gribble;
704   };
705 }
706
707 // Names beginning with "__": only for arguments and
708 //   local variables; never use "__" in a type name, or
709 //   within any name; never use "__[0-9]".
710
711 #endif /* _HEADER_ */
712
713
714 namespace std 
715 {
716   template&lt;typename T&gt;  // notice: "typename", not "class", no space
717     long_return_value_type&lt;with_many, args&gt;  
718     function_name(char* pointer,               // "char *pointer" is wrong.
719                   char* argument, 
720                   const Reference&amp; ref)
721     {
722       // int a_local;  /* wrong; see below. */
723       if (test) 
724       { 
725           nested code 
726       }
727     
728       int a_local = 0;  // declare variable at first use.
729
730       //  char a, b, *p;   /* wrong */
731       char a = 'a';
732       char b = a + 1;
733       char* c = "abc";  // each variable goes on its own line, always.
734
735       // except maybe here...
736       for (unsigned i = 0, mask = 1; mask; ++i, mask &lt;&lt;= 1) {
737           // ...
738       }
739     }
740   
741   gribble::gribble()
742   : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
743   { }
744
745   inline int 
746   gribble::three_lines()
747   {
748     // doesn't fit in one line.
749   }
750 } // namespace std
751
752
753 </literallayout>
754     </sect2>
755   </sect1>  
756
757   <sect1 id="contrib.doc_style" xreflabel="Documentation Style">
758     <title>Documentation Style</title>
759     <para>
760     </para>
761     <sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen">
762       <title>Doxygen</title>
763     <sect3 id="doxygen.generating" xreflabel="doxygen.generating">
764       <title>Generating the Doxygen Files</title>
765
766 <para>The Makefile rules <code>'make doc-doxygen-html'</code>,
767    and <code>'make doc-doxygen-man'</code> in the libstdc++ build
768    directory generate the HTML docs, the and the man pages,
769    respectively.  Prerequisite tools are Bash 2.x,
770    <ulink url="http://www.doxygen.org/">Doxygen</ulink>, a working version of <code>g++</code> somewhere in the PATH, and
771    the <ulink url="http://www.gnu.org/software/coreutils/">GNU coreutils</ulink>.
772
773    In addition, to generate the pretty pictures and hierarchy graphs, the 
774    <ulink url=
775    "http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink>
776    package will need to be installed.
777    (g++ is used to build a program which manipulates man pages.  GNU versions
778    of find, xargs, and possibly sed and grep are used, just because the GNU
779    versions make things very easy.)
780 </para>
781
782 <para>Careful observers will see that the Makefile rules simply call a script
783    from the source tree, <code>run_doxygen</code>, which does the actual work
784    of running Doxygen and then (most importantly) massaging the output files.
785    If for some reason you prefer to not go through the Makefile, you can call
786    this script directly.  (Start by passing <code>'--help'</code>.)
787 </para>
788
789 <para>If you wish to tweak the Doxygen settings, do so by editing
790    <code>docs/doxygen/user.cfg.in</code>.  Notes to v3-hackers are written in
791    triple-# comments.
792 </para>
793
794     </sect3>
795
796     <sect3 id="doxygen.markup" xreflabel="doxygen.markup">
797       <title>Markup</title>
798
799 <para>In general, libstdc++ files should be formatted according to the GNU
800    C++ Coding Standard rules found in the file
801    <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</ulink>.
802    Before any doxygen-specific formatting tweaks are made, please try to make
803    sure that the initial formatting is sound.
804 </para>
805
806 <para>Adding Doxygen markup to a file (informally called "doxygenating") is very
807    simple.  The Doxygen manual can be found
808    <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>.
809    We try to use a very-recent version of Doxygen.
810 </para>
811
812 <para>For classes, use deque/vector/list and std::pair as examples.  For
813    functions, see their member functions, and the free functions in
814    <code>stl_algobase.h</code>.  Member functions of other container-like
815    types should read similarly to these member functions.
816 </para>
817
818 <para>These points accompany the first list in section 3.1 of the Doxygen manual:
819 </para>
820 <orderedlist>
821  <listitem><para>Use the Javadoc style...</para></listitem>
822  <listitem><para>...not the Qt style.  The intermediate *'s are preferred.</para></listitem>
823  <listitem><para>Use the triple-slash style only for one-line comments (the "brief" mode).
824      Very recent versions of Doxygen permit full-mode comments in triple-slash
825      blocks, but the formatting still comes out wonky.</para></listitem>
826  <listitem><para>This is disgusting.  Don't do this.</para></listitem>
827 </orderedlist>
828
829 <para>Use the @-style of commands, not the !-style.  Please be careful about
830    whitespace in your markup comments.  Most of the time it doesn't matter;
831    doxygen absorbs most whitespace, and both HTML and *roff are agnostic about
832    whitespace.  However, in &lt;pre&gt; blocks and @code/@endcode sections,
833    spacing can have "interesting" effects.
834 </para>
835
836 <para>Use either kind of grouping, as appropriate.  <code>doxygroups.cc</code>
837    exists for this purpose.  See <code>stl_iterator.h</code> for a good
838    example of the "other" kind of grouping.
839 </para>
840
841 <para>Please use markup tags like @p and @a when referring to things such as the
842    names of function parameters.  Use @e for emphasis when necessary.  Use @c
843    to refer to other standard names.  (Examples of all these abound in the
844    present code.)
845 </para>
846
847     </sect3>
848
849     </sect2>
850
851     <sect2 id="doc_style.docbook" xreflabel="doc_style.docbook">
852       <title>Docbook</title>
853
854 <literallayout>
855  
856 Which files are important:
857
858 Main page
859 spine.xml               - index to documentation set
860
861 manual/spine.xml        - index to manual
862 manual/*.xml            - chapters and sections of the manual
863
864 faq.xml                 - index to FAQ
865 api.xml                 - index to source level / API 
866
867 All *.txml files are template xml files, ie otherwise empty files with
868 the correct structure, suitable for filling in.
869
870
871 Cannonical Writing Style
872
873 class template
874 function template
875 member function template
876 (via C++ Templates, Vandevoorde)
877
878 class in namespace std: allocator, not std::allocator
879
880 header file: iostream, not &lt;iostream&gt;
881
882
883 Translation
884
885 HTML to XML rough equivalents
886
887 &lt;p&gt;                       &lt;para&gt;
888
889 &lt;pre&gt;                     &lt;computeroutput&gt;
890 &lt;pre&gt;                     &lt;programlisting&gt;
891 &lt;pre&gt;                     &lt;literallayout&gt;
892
893 &lt;ul&gt;                      &lt;itemizedlist&gt;
894 &lt;ol&gt;                      &lt;orderedlist&gt;
895 &lt;il&gt;                      &lt;listitem&gt;
896
897 &lt;dl&gt;                      &lt;variablelist&gt;
898
899                         &lt;varlistentry&gt;
900 &lt;dt&gt;                        &lt;term&gt;
901 &lt;/dt&gt;                       &lt;/term&gt;
902 &lt;dd&gt;                        &lt;listitem&gt;
903 &lt;/dt&gt;                       &lt;/listitem&gt;
904                         &lt;/varlistentry&gt;
905
906 &lt;a href                      &lt;ulink url
907 &lt;code&gt;                    &lt;literal&gt;
908 &lt;code&gt;                    &lt;programlisting&gt;
909
910 &lt;strong&gt;          &lt;emphasis&gt;
911 &lt;em&gt;                      &lt;emphasis&gt;
912 &quot;                  &lt;quote&gt;
913
914 ctype.h                 &lt;filename class="headerfile"&gt;&lt;/filename&gt;
915
916    
917 build_dir               &lt;filename class="directory"&gt;path_to_build_dir&lt;/filename&gt;
918
919 Finer gradations of &lt;code&gt;
920
921 &lt;classname&gt;               &lt;classname&gt;string&lt;/classname&gt;
922                         &lt;classname&gt;vector&lt;&gt;&lt;/classname&gt;                       
923                         &lt;function&gt;fs.clear()&lt;/function&gt;
924
925 &lt;structname&gt;
926
927 &lt;function&gt;                &lt;function&gt;clear()&lt;/function&gt;
928
929 &lt;type&gt;                    &lt;type&gt;long long&lt;/type&gt;
930
931 &lt;varname&gt;         &lt;varname&gt;fs&lt;/varname&gt;
932
933 &lt;literal&gt;         &lt;literal&gt;-Weffc++&lt;/literal&gt; 
934                         &lt;literal&gt;rel_ops&lt;/literal&gt;
935
936 &lt;constant&gt;                &lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;
937                         &lt;constant&gt;3.0&lt;/constant&gt;
938
939 &lt;filename&gt;
940
941 &lt;command&gt;         &lt;command&gt;g++&lt;/command&gt;
942
943 &lt;errortext&gt;               &lt;errortext&gt;foo Concept &lt;/errortext&gt;
944
945
946 General structure
947
948 &lt;set&gt;
949   &lt;book&gt;
950   &lt;/book&gt;
951
952   &lt;book&gt;
953     &lt;chapter&gt;
954     &lt;/chapter&gt;
955   &lt;/book&gt;
956
957
958   &lt;book&gt;  
959     &lt;part&gt;
960       &lt;chapter&gt;
961         &lt;section&gt;
962         &lt;/section&gt;
963
964         &lt;sect1&gt;
965         &lt;/sect1&gt;
966
967         &lt;sect1&gt;
968           &lt;sect2&gt;
969           &lt;/sect2&gt;
970         &lt;/sect1&gt;
971       &lt;/chapter&gt;
972
973       &lt;chapter&gt;
974       &lt;/chapter&gt;
975     &lt;/part&gt;  
976   &lt;/book&gt;
977
978
979 &lt;/set&gt;
980
981 </literallayout>
982     </sect2>
983
984   </sect1>  
985
986   <sect1 id="contrib.design_notes" xreflabel="Design Notes">
987     <title>Design Notes</title>
988     <para>
989     </para>
990
991 <literallayout>
992
993 The Library
994 -----------
995
996 This paper is covers two major areas:
997
998  - Features and policies not mentioned in the standard that
999    the quality of the library implementation depends on, including
1000    extensions and "implementation-defined" features;
1001
1002  - Plans for required but unimplemented library features and
1003    optimizations to them.
1004
1005 Overhead
1006 --------
1007
1008 The standard defines a large library, much larger than the standard
1009 C library.  A naive implementation would suffer substantial overhead
1010 in compile time, executable size, and speed, rendering it unusable
1011 in many (particularly embedded) applications.  The alternative demands
1012 care in construction, and some compiler support, but there is no
1013 need for library subsets.
1014
1015 What are the sources of this overhead?  There are four main causes:
1016
1017  - The library is specified almost entirely as templates, which
1018    with current compilers must be included in-line, resulting in
1019    very slow builds as tens or hundreds of thousands of lines
1020    of function definitions are read for each user source file.
1021    Indeed, the entire SGI STL, as well as the dos Reis valarray,
1022    are provided purely as header files, largely for simplicity in
1023    porting.  Iostream/locale is (or will be) as large again.
1024
1025  - The library is very flexible, specifying a multitude of hooks
1026    where users can insert their own code in place of defaults.
1027    When these hooks are not used, any time and code expended to
1028    support that flexibility is wasted.
1029
1030  - Templates are often described as causing to "code bloat".  In
1031    practice, this refers (when it refers to anything real) to several
1032    independent processes.  First, when a class template is manually
1033    instantiated in its entirely, current compilers place the definitions
1034    for all members in a single object file, so that a program linking
1035    to one member gets definitions of all.  Second, template functions
1036    which do not actually depend on the template argument are, under
1037    current compilers, generated anew for each instantiation, rather
1038    than being shared with other instantiations.  Third, some of the
1039    flexibility mentioned above comes from virtual functions (both in
1040    regular classes and template classes) which current linkers add
1041    to the executable file even when they manifestly cannot be called.
1042
1043  - The library is specified to use a language feature, exceptions,
1044    which in the current gcc compiler ABI imposes a run time and
1045    code space cost to handle the possibility of exceptions even when
1046    they are not used.  Under the new ABI (accessed with -fnew-abi),
1047    there is a space overhead and a small reduction in code efficiency
1048    resulting from lost optimization opportunities associated with
1049    non-local branches associated with exceptions.
1050
1051 What can be done to eliminate this overhead?  A variety of coding
1052 techniques, and compiler, linker and library improvements and
1053 extensions may be used, as covered below.  Most are not difficult,
1054 and some are already implemented in varying degrees.
1055
1056 Overhead: Compilation Time
1057 --------------------------
1058
1059 Providing "ready-instantiated" template code in object code archives
1060 allows us to avoid generating and optimizing template instantiations
1061 in each compilation unit which uses them.  However, the number of such
1062 instantiations that are useful to provide is limited, and anyway this
1063 is not enough, by itself, to minimize compilation time.  In particular,
1064 it does not reduce time spent parsing conforming headers.
1065
1066 Quicker header parsing will depend on library extensions and compiler
1067 improvements.   One approach is some variation on the techniques
1068 previously marketed as "pre-compiled headers", now standardized as
1069 support for the "export" keyword.  "Exported" template definitions
1070 can be placed (once) in a "repository" -- really just a library, but
1071 of template definitions rather than object code -- to be drawn upon
1072 at link time when an instantiation is needed, rather than placed in
1073 header files to be parsed along with every compilation unit.
1074
1075 Until "export" is implemented we can put some of the lengthy template
1076 definitions in #if guards or alternative headers so that users can skip
1077 over the the full definitions when they need only the ready-instantiated
1078 specializations.
1079
1080 To be precise, this means that certain headers which define
1081 templates which users normally use only for certain arguments
1082 can be instrumented to avoid exposing the template definitions
1083 to the compiler unless a macro is defined.  For example, in
1084 &lt;string&gt;, we might have:
1085
1086    template &lt;class _CharT, ... &gt; class basic_string {
1087      ... // member declarations
1088    };
1089    ... // operator declarations
1090
1091    #ifdef _STRICT_ISO_
1092    # if _G_NO_TEMPLATE_EXPORT
1093    #   include &lt;bits/std_locale.h&gt;  // headers needed by definitions
1094    #   ...
1095    #   include &lt;bits/string.tcc&gt;  // member and global template definitions.
1096    # endif
1097    #endif
1098
1099 Users who compile without specifying a strict-ISO-conforming flag
1100 would not see many of the template definitions they now see, and rely
1101 instead on ready-instantiated specializations in the library.  This
1102 technique would be useful for the following substantial components:
1103 string, locale/iostreams, valarray.  It would *not* be useful or
1104 usable with the following: containers, algorithms, iterators,
1105 allocator.  Since these constitute a large (though decreasing)
1106 fraction of the library, the benefit the technique offers is
1107 limited.
1108
1109 The language specifies the semantics of the "export" keyword, but
1110 the gcc compiler does not yet support it.  When it does, problems
1111 with large template inclusions can largely disappear, given some
1112 minor library reorganization, along with the need for the apparatus
1113 described above.
1114
1115 Overhead: Flexibility Cost
1116 --------------------------
1117
1118 The library offers many places where users can specify operations
1119 to be performed by the library in place of defaults.  Sometimes
1120 this seems to require that the library use a more-roundabout, and
1121 possibly slower, way to accomplish the default requirements than
1122 would be used otherwise.
1123
1124 The primary protection against this overhead is thorough compiler
1125 optimization, to crush out layers of inline function interfaces.
1126 Kuck &amp; Associates has demonstrated the practicality of this kind
1127 of optimization.
1128
1129 The second line of defense against this overhead is explicit
1130 specialization.  By defining helper function templates, and writing
1131 specialized code for the default case, overhead can be eliminated
1132 for that case without sacrificing flexibility.  This takes full
1133 advantage of any ability of the optimizer to crush out degenerate
1134 code.
1135
1136 The library specifies many virtual functions which current linkers
1137 load even when they cannot be called.  Some minor improvements to the
1138 compiler and to ld would eliminate any such overhead by simply
1139 omitting virtual functions that the complete program does not call.
1140 A prototype of this work has already been done.  For targets where
1141 GNU ld is not used, a "pre-linker" could do the same job.
1142
1143 The main areas in the standard interface where user flexibility
1144 can result in overhead are:
1145
1146  - Allocators:  Containers are specified to use user-definable
1147    allocator types and objects, making tuning for the container
1148    characteristics tricky.
1149
1150  - Locales: the standard specifies locale objects used to implement
1151    iostream operations, involving many virtual functions which use
1152    streambuf iterators.
1153
1154  - Algorithms and containers: these may be instantiated on any type,
1155    frequently duplicating code for identical operations.
1156
1157  - Iostreams and strings: users are permitted to use these on their
1158    own types, and specify the operations the stream must use on these
1159    types.
1160
1161 Note that these sources of overhead are _avoidable_.  The techniques
1162 to avoid them are covered below.
1163
1164 Code Bloat
1165 ----------
1166
1167 In the SGI STL, and in some other headers, many of the templates
1168 are defined "inline" -- either explicitly or by their placement
1169 in class definitions -- which should not be inline.  This is a
1170 source of code bloat.  Matt had remarked that he was relying on
1171 the compiler to recognize what was too big to benefit from inlining,
1172 and generate it out-of-line automatically.  However, this also can
1173 result in code bloat except where the linker can eliminate the extra
1174 copies.
1175
1176 Fixing these cases will require an audit of all inline functions
1177 defined in the library to determine which merit inlining, and moving
1178 the rest out of line.  This is an issue mainly in chapters 23, 25, and
1179 27.  Of course it can be done incrementally, and we should generally
1180 accept patches that move large functions out of line and into ".tcc"
1181 files, which can later be pulled into a repository.  Compiler/linker
1182 improvements to recognize very large inline functions and move them
1183 out-of-line, but shared among compilation units, could make this
1184 work unnecessary.
1185
1186 Pre-instantiating template specializations currently produces large
1187 amounts of dead code which bloats statically linked programs.  The
1188 current state of the static library, libstdc++.a, is intolerable on
1189 this account, and will fuel further confused speculation about a need
1190 for a library "subset".  A compiler improvement that treats each
1191 instantiated function as a separate object file, for linking purposes,
1192 would be one solution to this problem.  An alternative would be to
1193 split up the manual instantiation files into dozens upon dozens of
1194 little files, each compiled separately, but an abortive attempt at
1195 this was done for &lt;string&gt; and, though it is far from complete, it
1196 is already a nuisance.  A better interim solution (just until we have
1197 "export") is badly needed.
1198
1199 When building a shared library, the current compiler/linker cannot
1200 automatically generate the instantiatiations needed.  This creates a
1201 miserable situation; it means any time something is changed in the
1202 library, before a shared library can be built someone must manually
1203 copy the declarations of all templates that are needed by other parts
1204 of the library to an "instantiation" file, and add it to the build
1205 system to be compiled and linked to the library.  This process is
1206 readily automated, and should be automated as soon as possible.
1207 Users building their own shared libraries experience identical
1208 frustrations.
1209
1210 Sharing common aspects of template definitions among instantiations
1211 can radically reduce code bloat.  The compiler could help a great
1212 deal here by recognizing when a function depends on nothing about
1213 a template parameter, or only on its size, and giving the resulting
1214 function a link-name "equate" that allows it to be shared with other
1215 instantiations.  Implementation code could take advantage of the
1216 capability by factoring out code that does not depend on the template
1217 argument into separate functions to be merged by the compiler.
1218
1219 Until such a compiler optimization is implemented, much can be done
1220 manually (if tediously) in this direction.  One such optimization is
1221 to derive class templates from non-template classes, and move as much
1222 implementation as possible into the base class.  Another is to partial-
1223 specialize certain common instantiations, such as vector&lt;T*&gt;, to share
1224 code for instantiations on all types T.  While these techniques work,
1225 they are far from the complete solution that a compiler improvement
1226 would afford.
1227
1228 Overhead: Expensive Language Features
1229 -------------------------------------
1230
1231 The main "expensive" language feature used in the standard library
1232 is exception support, which requires compiling in cleanup code with
1233 static table data to locate it, and linking in library code to use
1234 the table.  For small embedded programs the amount of such library
1235 code and table data is assumed by some to be excessive.  Under the
1236 "new" ABI this perception is generally exaggerated, although in some
1237 cases it may actually be excessive.
1238
1239 To implement a library which does not use exceptions directly is
1240 not difficult given minor compiler support (to "turn off" exceptions
1241 and ignore exception constructs), and results in no great library
1242 maintenance difficulties.  To be precise, given "-fno-exceptions",
1243 the compiler should treat "try" blocks as ordinary blocks, and
1244 "catch" blocks as dead code to ignore or eliminate.  Compiler
1245 support is not strictly necessary, except in the case of "function
1246 try blocks"; otherwise the following macros almost suffice:
1247
1248   #define throw(X)
1249   #define try      if (true)
1250   #define catch(X) else if (false)
1251
1252 However, there may be a need to use function try blocks in the
1253 library implementation, and use of macros in this way can make
1254 correct diagnostics impossible.  Furthermore, use of this scheme
1255 would require the library to call a function to re-throw exceptions
1256 from a try block.  Implementing the above semantics in the compiler
1257 is preferable.
1258
1259 Given the support above (however implemented) it only remains to
1260 replace code that "throws" with a call to a well-documented "handler"
1261 function in a separate compilation unit which may be replaced by
1262 the user.  The main source of exceptions that would be difficult
1263 for users to avoid is memory allocation failures, but users can
1264 define their own memory allocation primitives that never throw.
1265 Otherwise, the complete list of such handlers, and which library
1266 functions may call them, would be needed for users to be able to
1267 implement the necessary substitutes.  (Fortunately, they have the
1268 source code.)
1269
1270 Opportunities
1271 -------------
1272
1273 The template capabilities of C++ offer enormous opportunities for
1274 optimizing common library operations, well beyond what would be
1275 considered "eliminating overhead".  In particular, many operations
1276 done in Glibc with macros that depend on proprietary language
1277 extensions can be implemented in pristine Standard C++.  For example,
1278 the chapter 25 algorithms, and even C library functions such as strchr,
1279 can be specialized for the case of static arrays of known (small) size.
1280
1281 Detailed optimization opportunities are identified below where
1282 the component where they would appear is discussed.  Of course new
1283 opportunities will be identified during implementation.
1284
1285 Unimplemented Required Library Features
1286 ---------------------------------------
1287
1288 The standard specifies hundreds of components, grouped broadly by
1289 chapter.  These are listed in excruciating detail in the CHECKLIST
1290 file.
1291
1292   17 general
1293   18 support
1294   19 diagnostics
1295   20 utilities
1296   21 string
1297   22 locale
1298   23 containers
1299   24 iterators
1300   25 algorithms
1301   26 numerics
1302   27 iostreams
1303   Annex D  backward compatibility
1304
1305 Anyone participating in implementation of the library should obtain
1306 a copy of the standard, ISO 14882.   People in the U.S. can obtain an
1307 electronic copy for US$18 from ANSI's web site.  Those from other
1308 countries should visit http://www.iso.ch/ to find out the location
1309 of their country's representation in ISO, in order to know who can
1310 sell them a copy.
1311
1312 The emphasis in the following sections is on unimplemented features
1313 and optimization opportunities.
1314
1315 Chapter 17  General
1316 -------------------
1317
1318 Chapter 17 concerns overall library requirements.
1319
1320 The standard doesn't mention threads.  A multi-thread (MT) extension
1321 primarily affects operators new and delete (18), allocator (20),
1322 string (21), locale (22), and iostreams (27).  The common underlying
1323 support needed for this is discussed under chapter 20.
1324
1325 The standard requirements on names from the C headers create a
1326 lot of work, mostly done.  Names in the C headers must be visible
1327 in the std:: and sometimes the global namespace; the names in the
1328 two scopes must refer to the same object.  More stringent is that
1329 Koenig lookup implies that any types specified as defined in std::
1330 really are defined in std::.  Names optionally implemented as
1331 macros in C cannot be macros in C++.  (An overview may be read at
1332 &lt;http://www.cantrip.org/cheaders.html&gt;).  The scripts "inclosure"
1333 and "mkcshadow", and the directories shadow/ and cshadow/, are the
1334 beginning of an effort to conform in this area.
1335
1336 A correct conforming definition of C header names based on underlying
1337 C library headers, and practical linking of conforming namespaced
1338 customer code with third-party C libraries depends ultimately on
1339 an ABI change, allowing namespaced C type names to be mangled into
1340 type names as if they were global, somewhat as C function names in a
1341 namespace, or C++ global variable names, are left unmangled.  Perhaps
1342 another "extern" mode, such as 'extern "C-global"' would be an
1343 appropriate place for such type definitions.  Such a type would
1344 affect mangling as follows:
1345
1346   namespace A {
1347     struct X {};
1348     extern "C-global" {  // or maybe just 'extern "C"'
1349       struct Y {};
1350     };
1351   }
1352   void f(A::X*);  // mangles to f__FPQ21A1X
1353   void f(A::Y*);  // mangles to f__FP1Y
1354
1355 (It may be that this is really the appropriate semantics for regular
1356 'extern "C"', and 'extern "C-global"', as an extension, would not be
1357 necessary.) This would allow functions declared in non-standard C headers
1358 (and thus fixable by neither us nor users) to link properly with functions
1359 declared using C types defined in properly-namespaced headers.  The
1360 problem this solves is that C headers (which C++ programmers do persist
1361 in using) frequently forward-declare C struct tags without including
1362 the header where the type is defined, as in
1363
1364   struct tm;
1365   void munge(tm*);
1366
1367 Without some compiler accommodation, munge cannot be called by correct
1368 C++ code using a pointer to a correctly-scoped tm* value.
1369
1370 The current C headers use the preprocessor extension "#include_next",
1371 which the compiler complains about when run "-pedantic".
1372 (Incidentally, it appears that "-fpedantic" is currently ignored,
1373 probably a bug.)  The solution in the C compiler is to use
1374 "-isystem" rather than "-I", but unfortunately in g++ this seems
1375 also to wrap the whole header in an 'extern "C"' block, so it's
1376 unusable for C++ headers.  The correct solution appears to be to
1377 allow the various special include-directory options, if not given
1378 an argument, to affect subsequent include-directory options additively,
1379 so that if one said
1380
1381   -pedantic -iprefix $(prefix) \
1382   -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \
1383   -iwithprefix -I g++-v3/ext
1384
1385 the compiler would search $(prefix)/g++-v3 and not report
1386 pedantic warnings for files found there, but treat files in
1387 $(prefix)/g++-v3/ext pedantically.  (The undocumented semantics
1388 of "-isystem" in g++ stink.  Can they be rescinded?  If not it
1389 must be replaced with something more rationally behaved.)
1390
1391 All the C headers need the treatment above; in the standard these
1392 headers are mentioned in various chapters.  Below, I have only
1393 mentioned those that present interesting implementation issues.
1394
1395 The components identified as "mostly complete", below, have not been
1396 audited for conformance.  In many cases where the library passes
1397 conformance tests we have non-conforming extensions that must be
1398 wrapped in #if guards for "pedantic" use, and in some cases renamed
1399 in a conforming way for continued use in the implementation regardless
1400 of conformance flags.
1401
1402 The STL portion of the library still depends on a header
1403 stl/bits/stl_config.h full of #ifdef clauses.  This apparatus
1404 should be replaced with autoconf/automake machinery.
1405
1406 The SGI STL defines a type_traits&lt;&gt; template, specialized for
1407 many types in their code including the built-in numeric and
1408 pointer types and some library types, to direct optimizations of
1409 standard functions.  The SGI compiler has been extended to generate
1410 specializations of this template automatically for user types,
1411 so that use of STL templates on user types can take advantage of
1412 these optimizations.  Specializations for other, non-STL, types
1413 would make more optimizations possible, but extending the gcc
1414 compiler in the same way would be much better.  Probably the next
1415 round of standardization will ratify this, but probably with
1416 changes, so it probably should be renamed to place it in the
1417 implementation namespace.
1418
1419 The SGI STL also defines a large number of extensions visible in
1420 standard headers.  (Other extensions that appear in separate headers
1421 have been sequestered in subdirectories ext/ and backward/.)  All
1422 these extensions should be moved to other headers where possible,
1423 and in any case wrapped in a namespace (not std!), and (where kept
1424 in a standard header) girded about with macro guards.  Some cannot be
1425 moved out of standard headers because they are used to implement
1426 standard features.   The canonical method for accommodating these
1427 is to use a protected name, aliased in macro guards to a user-space
1428 name.  Unfortunately C++ offers no satisfactory template typedef
1429 mechanism, so very ad-hoc and unsatisfactory aliasing must be used
1430 instead.
1431
1432 Implementation of a template typedef mechanism should have the highest
1433 priority among possible extensions, on the same level as implementation
1434 of the template "export" feature.
1435
1436 Chapter 18  Language support
1437 ----------------------------
1438
1439 Headers: &lt;limits&gt; &lt;new&gt; &lt;typeinfo&gt; &lt;exception&gt;
1440 C headers: &lt;cstddef&gt; &lt;climits&gt; &lt;cfloat&gt;  &lt;cstdarg&gt; &lt;csetjmp&gt;
1441            &lt;ctime&gt;   &lt;csignal&gt; &lt;cstdlib&gt; (also 21, 25, 26)
1442
1443 This defines the built-in exceptions, rtti, numeric_limits&lt;&gt;,
1444 operator new and delete.  Much of this is provided by the
1445 compiler in its static runtime library.
1446
1447 Work to do includes defining numeric_limits&lt;&gt; specializations in
1448 separate files for all target architectures.  Values for integer types
1449 except for bool and wchar_t are readily obtained from the C header
1450 &lt;limits.h&gt;, but values for the remaining numeric types (bool, wchar_t,
1451 float, double, long double) must be entered manually.  This is
1452 largely dog work except for those members whose values are not
1453 easily deduced from available documentation.  Also, this involves
1454 some work in target configuration to identify the correct choice of
1455 file to build against and to install.
1456
1457 The definitions of the various operators new and delete must be
1458 made thread-safe, which depends on a portable exclusion mechanism,
1459 discussed under chapter 20.   Of course there is always plenty of
1460 room for improvements to the speed of operators new and delete.
1461
1462 &lt;cstdarg&gt;, in Glibc, defines some macros that gcc does not allow to
1463 be wrapped into an inline function.  Probably this header will demand
1464 attention whenever a new target is chosen.  The functions atexit(),
1465 exit(), and abort() in cstdlib have different semantics in C++, so
1466 must be re-implemented for C++.
1467
1468 Chapter 19  Diagnostics
1469 -----------------------
1470
1471 Headers: &lt;stdexcept&gt;
1472 C headers: &lt;cassert&gt; &lt;cerrno&gt;
1473
1474 This defines the standard exception objects, which are "mostly complete".
1475 Cygnus has a version, and now SGI provides a slightly different one.
1476 It makes little difference which we use.
1477
1478 The C global name "errno", which C allows to be a variable or a macro,
1479 is required in C++ to be a macro.  For MT it must typically result in
1480 a function call.
1481
1482 Chapter 20  Utilities
1483 ---------------------
1484 Headers: &lt;utility&gt; &lt;functional&gt; &lt;memory&gt;
1485 C header: &lt;ctime&gt; (also in 18)
1486
1487 SGI STL provides "mostly complete" versions of all the components
1488 defined in this chapter.  However, the auto_ptr&lt;&gt; implementation
1489 is known to be wrong.  Furthermore, the standard definition of it
1490 is known to be unimplementable as written.  A minor change to the
1491 standard would fix it, and auto_ptr&lt;&gt; should be adjusted to match.
1492
1493 Multi-threading affects the allocator implementation, and there must
1494 be configuration/installation choices for different users' MT
1495 requirements.  Anyway, users will want to tune allocator options
1496 to support different target conditions, MT or no.
1497
1498 The primitives used for MT implementation should be exposed, as an
1499 extension, for users' own work.  We need cross-CPU "mutex" support,
1500 multi-processor shared-memory atomic integer operations, and single-
1501 processor uninterruptible integer operations, and all three configurable
1502 to be stubbed out for non-MT use, or to use an appropriately-loaded
1503 dynamic library for the actual runtime environment, or statically
1504 compiled in for cases where the target architecture is known.
1505
1506 Chapter 21  String
1507 ------------------
1508 Headers: &lt;string&gt;
1509 C headers: &lt;cctype&gt; &lt;cwctype&gt; &lt;cstring&gt; &lt;cwchar&gt; (also in 27)
1510            &lt;cstdlib&gt; (also in 18, 25, 26)
1511
1512 We have "mostly-complete" char_traits&lt;&gt; implementations.  Many of the
1513 char_traits&lt;char&gt; operations might be optimized further using existing
1514 proprietary language extensions.
1515
1516 We have a "mostly-complete" basic_string&lt;&gt; implementation.  The work
1517 to manually instantiate char and wchar_t specializations in object
1518 files to improve link-time behavior is extremely unsatisfactory,
1519 literally tripling library-build time with no commensurate improvement
1520 in static program link sizes.  It must be redone.  (Similar work is
1521 needed for some components in chapters 22 and 27.)
1522
1523 Other work needed for strings is MT-safety, as discussed under the
1524 chapter 20 heading.
1525
1526 The standard C type mbstate_t from &lt;cwchar&gt; and used in char_traits&lt;&gt;
1527 must be different in C++ than in C, because in C++ the default constructor
1528 value mbstate_t() must be the "base" or "ground" sequence state.
1529 (According to the likely resolution of a recently raised Core issue,
1530 this may become unnecessary.  However, there are other reasons to
1531 use a state type not as limited as whatever the C library provides.)
1532 If we might want to provide conversions from (e.g.) internally-
1533 represented EUC-wide to externally-represented Unicode, or vice-
1534 versa, the mbstate_t we choose will need to be more accommodating
1535 than what might be provided by an underlying C library.
1536
1537 There remain some basic_string template-member functions which do
1538 not overload properly with their non-template brethren.  The infamous
1539 hack akin to what was done in vector&lt;&gt; is needed, to conform to
1540 23.1.1 para 10.  The CHECKLIST items for basic_string marked 'X',
1541 or incomplete, are so marked for this reason.
1542
1543 Replacing the string iterators, which currently are simple character
1544 pointers, with class objects would greatly increase the safety of the
1545 client interface, and also permit a "debug" mode in which range,
1546 ownership, and validity are rigorously checked.  The current use of
1547 raw pointers as string iterators is evil.  vector&lt;&gt; iterators need the
1548 same treatment.  Note that the current implementation freely mixes
1549 pointers and iterators, and that must be fixed before safer iterators
1550 can be introduced.
1551
1552 Some of the functions in &lt;cstring&gt; are different from the C version.
1553 generally overloaded on const and non-const argument pointers.  For
1554 example, in &lt;cstring&gt; strchr is overloaded.  The functions isupper
1555 etc.  in &lt;cctype&gt; typically implemented as macros in C are functions
1556 in C++, because they are overloaded with others of the same name
1557 defined in &lt;locale&gt;.
1558
1559 Many of the functions required in &lt;cwctype&gt; and &lt;cwchar&gt; cannot be
1560 implemented using underlying C facilities on intended targets because
1561 such facilities only partly exist.
1562
1563 Chapter 22  Locale
1564 ------------------
1565 Headers: &lt;locale&gt;
1566 C headers: &lt;clocale&gt;
1567
1568 We have a "mostly complete" class locale, with the exception of
1569 code for constructing, and handling the names of, named locales.
1570 The ways that locales are named (particularly when categories
1571 (e.g. LC_TIME, LC_COLLATE) are different) varies among all target
1572 environments.  This code must be written in various versions and
1573 chosen by configuration parameters.
1574
1575 Members of many of the facets defined in &lt;locale&gt; are stubs.  Generally,
1576 there are two sets of facets: the base class facets (which are supposed
1577 to implement the "C" locale) and the "byname" facets, which are supposed
1578 to read files to determine their behavior.  The base ctype&lt;&gt;, collate&lt;&gt;,
1579 and numpunct&lt;&gt; facets are "mostly complete", except that the table of
1580 bitmask values used for "is" operations, and corresponding mask values,
1581 are still defined in libio and just included/linked.  (We will need to
1582 implement these tables independently, soon, but should take advantage
1583 of libio where possible.)  The num_put&lt;&gt;::put members for integer types
1584 are "mostly complete".
1585
1586 A complete list of what has and has not been implemented may be
1587 found in CHECKLIST.  However, note that the current definition of
1588 codecvt&lt;wchar_t,char,mbstate_t&gt; is wrong.  It should simply write
1589 out the raw bytes representing the wide characters, rather than
1590 trying to convert each to a corresponding single "char" value.
1591
1592 Some of the facets are more important than others.  Specifically,
1593 the members of ctype&lt;&gt;, numpunct&lt;&gt;, num_put&lt;&gt;, and num_get&lt;&gt; facets
1594 are used by other library facilities defined in &lt;string&gt;, &lt;istream&gt;,
1595 and &lt;ostream&gt;, and the codecvt&lt;&gt; facet is used by basic_filebuf&lt;&gt;
1596 in &lt;fstream&gt;, so a conforming iostream implementation depends on
1597 these.
1598
1599 The "long long" type eventually must be supported, but code mentioning
1600 it should be wrapped in #if guards to allow pedantic-mode compiling.
1601
1602 Performance of num_put&lt;&gt; and num_get&lt;&gt; depend critically on
1603 caching computed values in ios_base objects, and on extensions
1604 to the interface with streambufs.
1605
1606 Specifically: retrieving a copy of the locale object, extracting
1607 the needed facets, and gathering data from them, for each call to
1608 (e.g.) operator&lt;&lt; would be prohibitively slow.   To cache format
1609 data for use by num_put&lt;&gt; and num_get&lt;&gt; we have a _Format_cache&lt;&gt;
1610 object stored in the ios_base::pword() array.  This is constructed
1611 and initialized lazily, and is organized purely for utility.  It
1612 is discarded when a new locale with different facets is imbued.
1613
1614 Using only the public interfaces of the iterator arguments to the
1615 facet functions would limit performance by forbidding "vector-style"
1616 character operations.  The streambuf iterator optimizations are
1617 described under chapter 24, but facets can also bypass the streambuf
1618 iterators via explicit specializations and operate directly on the
1619 streambufs, and use extended interfaces to get direct access to the
1620 streambuf internal buffer arrays.  These extensions are mentioned
1621 under chapter 27.  These optimizations are particularly important
1622 for input parsing.
1623
1624 Unused virtual members of locale facets can be omitted, as mentioned
1625 above, by a smart linker.
1626
1627 Chapter 23  Containers
1628 ----------------------
1629 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;
1630
1631 All the components in chapter 23 are implemented in the SGI STL.
1632 They are "mostly complete"; they include a large number of
1633 nonconforming extensions which must be wrapped.  Some of these
1634 are used internally and must be renamed or duplicated.
1635
1636 The SGI components are optimized for large-memory environments.  For
1637 embedded targets, different criteria might be more appropriate.  Users
1638 will want to be able to tune this behavior.  We should provide
1639 ways for users to compile the library with different memory usage
1640 characteristics.
1641
1642 A lot more work is needed on factoring out common code from different
1643 specializations to reduce code size here and in chapter 25.  The
1644 easiest fix for this would be a compiler/ABI improvement that allows
1645 the compiler to recognize when a specialization depends only on the
1646 size (or other gross quality) of a template argument, and allow the
1647 linker to share the code with similar specializations.  In its
1648 absence, many of the algorithms and containers can be partial-
1649 specialized, at least for the case of pointers, but this only solves
1650 a small part of the problem.  Use of a type_traits-style template
1651 allows a few more optimization opportunities, more if the compiler
1652 can generate the specializations automatically.
1653
1654 As an optimization, containers can specialize on the default allocator
1655 and bypass it, or take advantage of details of its implementation
1656 after it has been improved upon.
1657
1658 Replacing the vector iterators, which currently are simple element
1659 pointers, with class objects would greatly increase the safety of the
1660 client interface, and also permit a "debug" mode in which range,
1661 ownership, and validity are rigorously checked.  The current use of
1662 pointers for iterators is evil.
1663
1664 As mentioned for chapter 24, the deque iterator is a good example of
1665 an opportunity to implement a "staged" iterator that would benefit
1666 from specializations of some algorithms.
1667
1668 Chapter 24  Iterators
1669 ---------------------
1670 Headers: &lt;iterator&gt;
1671
1672 Standard iterators are "mostly complete", with the exception of
1673 the stream iterators, which are not yet templatized on the
1674 stream type.  Also, the base class template iterator&lt;&gt; appears
1675 to be wrong, so everything derived from it must also be wrong,
1676 currently.
1677
1678 The streambuf iterators (currently located in stl/bits/std_iterator.h,
1679 but should be under bits/) can be rewritten to take advantage of
1680 friendship with the streambuf implementation.
1681
1682 Matt Austern has identified opportunities where certain iterator
1683 types, particularly including streambuf iterators and deque
1684 iterators, have a "two-stage" quality, such that an intermediate
1685 limit can be checked much more quickly than the true limit on
1686 range operations.  If identified with a member of iterator_traits,
1687 algorithms may be specialized for this case.  Of course the
1688 iterators that have this quality can be identified by specializing
1689 a traits class.
1690
1691 Many of the algorithms must be specialized for the streambuf
1692 iterators, to take advantage of block-mode operations, in order
1693 to allow iostream/locale operations' performance not to suffer.
1694 It may be that they could be treated as staged iterators and
1695 take advantage of those optimizations.
1696
1697 Chapter 25  Algorithms
1698 ----------------------
1699 Headers: &lt;algorithm&gt;
1700 C headers: &lt;cstdlib&gt; (also in 18, 21, 26))
1701
1702 The algorithms are "mostly complete".  As mentioned above, they
1703 are optimized for speed at the expense of code and data size.
1704
1705 Specializations of many of the algorithms for non-STL types would
1706 give performance improvements, but we must use great care not to
1707 interfere with fragile template overloading semantics for the
1708 standard interfaces.  Conventionally the standard function template
1709 interface is an inline which delegates to a non-standard function
1710 which is then overloaded (this is already done in many places in
1711 the library).  Particularly appealing opportunities for the sake of
1712 iostream performance are for copy and find applied to streambuf
1713 iterators or (as noted elsewhere) for staged iterators, of which
1714 the streambuf iterators are a good example.
1715
1716 The bsearch and qsort functions cannot be overloaded properly as
1717 required by the standard because gcc does not yet allow overloading
1718 on the extern-"C"-ness of a function pointer.
1719
1720 Chapter 26  Numerics
1721 --------------------
1722 Headers: &lt;complex&gt; &lt;valarray&gt; &lt;numeric&gt;
1723 C headers: &lt;cmath&gt;, &lt;cstdlib&gt; (also 18, 21, 25)
1724
1725 Numeric components: Gabriel dos Reis's valarray, Drepper's complex,
1726 and the few algorithms from the STL are "mostly done".   Of course
1727 optimization opportunities abound for the numerically literate.  It
1728 is not clear whether the valarray implementation really conforms
1729 fully, in the assumptions it makes about aliasing (and lack thereof)
1730 in its arguments.
1731
1732 The C div() and ldiv() functions are interesting, because they are the
1733 only case where a C library function returns a class object by value.
1734 Since the C++ type div_t must be different from the underlying C type
1735 (which is in the wrong namespace) the underlying functions div() and
1736 ldiv() cannot be re-used efficiently.  Fortunately they are trivial to
1737 re-implement.
1738
1739 Chapter 27  Iostreams
1740 ---------------------
1741 Headers: &lt;iosfwd&gt; &lt;streambuf&gt; &lt;ios&gt; &lt;ostream&gt; &lt;istream&gt; &lt;iostream&gt;
1742          &lt;iomanip&gt; &lt;sstream&gt; &lt;fstream&gt;
1743 C headers: &lt;cstdio&gt; &lt;cwchar&gt; (also in 21)
1744
1745 Iostream is currently in a very incomplete state.  &lt;iosfwd&gt;, &lt;iomanip&gt;,
1746 ios_base, and basic_ios&lt;&gt; are "mostly complete".  basic_streambuf&lt;&gt; and
1747 basic_ostream&lt;&gt; are well along, but basic_istream&lt;&gt; has had little work
1748 done.  The standard stream objects, &lt;sstream&gt; and &lt;fstream&gt; have been
1749 started; basic_filebuf&lt;&gt; "write" functions have been implemented just
1750 enough to do "hello, world".
1751
1752 Most of the istream and ostream operators &lt;&lt; and &gt;&gt; (with the exception
1753 of the op&lt;&lt;(integer) ones) have not been changed to use locale primitives,
1754 sentry objects, or char_traits members.
1755
1756 All these templates should be manually instantiated for char and
1757 wchar_t in a way that links only used members into user programs.
1758
1759 Streambuf is fertile ground for optimization extensions.  An extended
1760 interface giving iterator access to its internal buffer would be very
1761 useful for other library components.
1762
1763 Iostream operations (primarily operators &lt;&lt; and &gt;&gt;) can take advantage
1764 of the case where user code has not specified a locale, and bypass locale
1765 operations entirely.  The current implementation of op&lt;&lt;/num_put&lt;&gt;::put,
1766 for the integer types, demonstrates how they can cache encoding details
1767 from the locale on each operation.  There is lots more room for
1768 optimization in this area.
1769
1770 The definition of the relationship between the standard streams
1771 cout et al. and stdout et al. requires something like a "stdiobuf".
1772 The SGI solution of using double-indirection to actually use a
1773 stdio FILE object for buffering is unsatisfactory, because it
1774 interferes with peephole loop optimizations.
1775
1776 The &lt;sstream&gt; header work has begun.  stringbuf can benefit from
1777 friendship with basic_string&lt;&gt; and basic_string&lt;&gt;::_Rep to use
1778 those objects directly as buffers, and avoid allocating and making
1779 copies.
1780
1781 The basic_filebuf&lt;&gt; template is a complex beast.  It is specified to
1782 use the locale facet codecvt&lt;&gt; to translate characters between native
1783 files and the locale character encoding.  In general this involves
1784 two buffers, one of "char" representing the file and another of
1785 "char_type", for the stream, with codecvt&lt;&gt; translating.  The process
1786 is complicated by the variable-length nature of the translation, and
1787 the need to seek to corresponding places in the two representations.
1788 For the case of basic_filebuf&lt;char&gt;, when no translation is needed,
1789 a single buffer suffices.  A specialized filebuf can be used to reduce
1790 code space overhead when no locale has been imbued.  Matt Austern's
1791 work at SGI will be useful, perhaps directly as a source of code, or
1792 at least as an example to draw on.
1793
1794 Filebuf, almost uniquely (cf. operator new), depends heavily on
1795 underlying environmental facilities.  In current releases iostream
1796 depends fairly heavily on libio constant definitions, but it should
1797 be made independent.   It also depends on operating system primitives
1798 for file operations.  There is immense room for optimizations using
1799 (e.g.) mmap for reading.  The shadow/ directory wraps, besides the
1800 standard C headers, the libio.h and unistd.h headers, for use mainly
1801 by filebuf.  These wrappings have not been completed, though there
1802 is scaffolding in place.
1803
1804 The encapulation of certain C header &lt;cstdio&gt; names presents an
1805 interesting problem.  It is possible to define an inline std::fprintf()
1806 implemented in terms of the 'extern "C"' vfprintf(), but there is no
1807 standard vfscanf() to use to implement std::fscanf().  It appears that
1808 vfscanf but be re-implemented in C++ for targets where no vfscanf
1809 extension has been defined.  This is interesting in that it seems
1810 to be the only significant case in the C library where this kind of
1811 rewriting is necessary.  (Of course Glibc provides the vfscanf()
1812 extension.)  (The functions related to exit() must be rewritten
1813 for other reasons.)
1814
1815
1816 Annex D
1817 -------
1818 Headers: &lt;strstream&gt;
1819
1820 Annex D defines many non-library features, and many minor
1821 modifications to various headers, and a complete header.
1822 It is "mostly done", except that the libstdc++-2 &lt;strstream&gt;
1823 header has not been adopted into the library, or checked to
1824 verify that it matches the draft in those details that were
1825 clarified by the committee.  Certainly it must at least be
1826 moved into the std namespace.
1827
1828 We still need to wrap all the deprecated features in #if guards
1829 so that pedantic compile modes can detect their use.
1830
1831 Nonstandard Extensions
1832 ----------------------
1833 Headers: &lt;iostream.h&gt; &lt;strstream.h&gt; &lt;hash&gt; &lt;rbtree&gt;
1834          &lt;pthread_alloc&gt; &lt;stdiobuf&gt; (etc.)
1835
1836 User code has come to depend on a variety of nonstandard components
1837 that we must not omit.  Much of this code can be adopted from
1838 libstdc++-v2 or from the SGI STL.  This particularly includes
1839 &lt;iostream.h&gt;, &lt;strstream.h&gt;, and various SGI extensions such
1840 as &lt;hash_map.h&gt;.  Many of these are already placed in the
1841 subdirectories ext/ and backward/.  (Note that it is better to
1842 include them via "&lt;backward/hash_map.h&gt;" or "&lt;ext/hash_map&gt;" than
1843 to search the subdirectory itself via a "-I" directive.
1844 </literallayout>
1845   </sect1>  
1846
1847 </appendix>