contrib/gcc/cp/templates.texi

   1 @node Templates
   2 @chapter The Template Implementation
   3
   4 @cindex templates
   5 @cindex function templates
   6 @cindex class templates
   7 @cindex parameterized types
   8 @cindex types, parameterized
   9 The C++ template@footnote{Class templates are also known as
  10 @dfn{parameterized types}.} facility, which effectively allows use of
  11 variables for types in declarations, is one of the newest features of
  12 the language.
  13
  14 @sc{gnu} C++ is one of the first compilers to implement many
  15 of the template facilities currently defined by the @sc{ansi} committee.
  16
  17 Nevertheless, the template implementation is not yet complete.  This
  18 chapter maps the current limitations of the @sc{gnu} C++ template
  19 implementation.
  20
  21 @menu
  22 * Template limitations:: Limitations for function and class templates
  23 * Function templates::   Limitations for function templates
  24 * Class templates::      Limitations for class templates
  25 * Template debugging::   Debugging information for templates
  26 @end menu
  27
  28 @node Template limitations
  29 @section Limitations for function and class templates
  30
  31 @cindex template limitations
  32 @cindex template bugs
  33 @cindex bugs, templates
  34 These limitations apply to any use of templates (function templates or
  35 class templates) with @sc{gnu} C++:
  36
  37 @table @emph
  38 @item Template definitions must be visible
  39 When you compile code with templates, the template definitions must come
  40 first (before the compiler needs to expand them), and template
  41 definitions you use must be visible in the current scope.
  42 @c FIXME! Is this a defined property of templates, rather than a
  43 @c temporary limitation?
  44 @c ANSWER: It's a limitation, but it's hard to say why it's a limitation
  45 @c to someone.  We need an infinite link-cycle, in one camp, to
  46 @c accomplish things so you don't need the template definitions around.
  47
  48 @cindex static data in template classes
  49 @cindex template classes, static data in
  50 @item Individual initializers needed for static data
  51 Templates for static data in template classes do not work.  @xref{Class
  52 templates,,Limitations for class templates}.
  53 @end table
  54
  55 @node Function templates
  56 @section Limitations for function templates
  57
  58 @cindex function template limitations
  59 Function templates are implemented for the most part.  The compiler can
  60 correctly determine template parameter values, and will delay
  61 instantiation of a function that uses templates until the requisite type
  62 information is available.
  63
  64 @noindent
  65 The following limitations remain:
  66
  67 @itemize @bullet
  68 @cindex template vs declaration, functions
  69 @cindex declaration vs template, functions
  70 @cindex function declaration vs template
  71 @item
  72 Narrowed specification: function declarations should not prevent
  73 template expansion.  When you declare a function, @sc{gnu} C++
  74 interprets the declaration as an indication that you will provide a
  75 definition for that function.  Therefore, @sc{gnu} C++ does not use a
  76 template expansion if there is also an applicable declaration.  @sc{gnu}
  77 C++ only expands the template when there is no such declaration.
  78
  79 The specification in Bjarne Stroustrup's @cite{The C++ Programming
  80 Language, Second Edition} is narrower, and the @sc{gnu} C++
  81 implementation is now clearly incorrect.  With this new specification, a
  82 declaration that corresponds to an instantiation of a function template
  83 only affects whether conversions are needed to use that version of the
  84 function.  It should no longer prevent expansion of the template
  85 definition.
  86
  87 For example, this code fragment must be treated differently:
  88
  89 @smallexample
  90 template <class X> X min (X& x1, X& x2) @{ @dots{} @}
  91 int min (int, int);
  92 @dots{}
  93 int i; short s;
  94 min (i, s); // @r{should call} min(int,int)
  95             // @r{derived from template}
  96 @dots{}
  97 @end smallexample
  98
  99 @item
 100 The compiler does not yet understand function signatures where types are
 101 nested within template parameters.  For example, a function like the
 102 following produces a syntax error on the closing @samp{)} of the
 103 definition of the function @code{f}:
 104
 105 @smallexample
 106 template <class T> class A @{ public: T x; class Y @{@}; @};
 107 template <class X> int f (A<X>::Y y) @{ @dots{} @}
 108 @end smallexample
 109
 110 @cindex @code{inline} and function templates
 111 @cindex function templates and @code{inline}
 112 @item
 113 If you declare an @code{inline} function using templates, the compiler
 114 can only inline the code @emph{after} the first time you use
 115 that function with whatever particular type signature the template
 116 was instantiated.
 117
 118 Removing this limitation is akin to supporting nested function
 119 definitions in @sc{gnu} C++; the limitation will probably remain until the
 120 more general problem of nested functions is solved.
 121
 122 @item
 123 All the @emph{method} templates (templates for member functions) for a
 124 class must be visible to the compiler when the class template is
 125 instantiated.
 126 @end itemize
 127
 128 @node Class templates
 129 @section Limitations for class templates
 130
 131 @cindex class template limitations
 132 @ignore
 133 FIXME!!  Include a comprehensible version of this if someone can explain it.
 134          (Queried Brendan and Raeburn w/full orig context, 26may1993---pesch)
 135    - [RHP: I don't understand what the following fragment refers to.  If it's
 136      the "BIG BUG" section in the original, why does it say "overriding class
 137      declarations" here when the more detailed text refers to *function*
 138      declarations?  Here's the fragment I don't understand:]
 139      there are problems with user-supplied overriding class declarations (see
 140      below).
 141 @end ignore
 142
 143 @itemize @bullet
 144 @ignore
 145 @cindex static data, not working in templates
 146 @item
 147 Templates for static data in template classes do not work.
 148 Currently, you must initialize each case of such data
 149 individually.
 150 @c FIXME!! Brendan to see if still true.
 151 @c ANSWER: This section presumes that it's incorrect to have to
 152 @c initialize for each type you instantiate with.  It's not, it's the
 153 @c right way to do it.
 154 @end ignore
 155
 156 Unfortunately, individual initializations of this sort are likely to be
 157 considered errors eventually; since they're needed now, you might want to
 158 flag places where you use them with comments to mark the need for a
 159 future transition.
 160
 161 @cindex nested type results vs templates
 162 @item
 163 Member functions in template classes may not have results of nested
 164 type; @sc{gnu} C++ signals a syntax error on the attempt.  The following
 165 example illustrates this problem with an @code{enum} type @code{alph}:
 166
 167 @smallexample
 168 template <class T> class list @{
 169   @dots{}
 170   enum alph @{a,b,c@};
 171   alph bar();
 172   @dots{}
 173 @};
 174
 175 template <class T>
 176 list<int>::alph list<int>::bar()  // @i{Syntax error here}
 177 @{
 178 @dots{}
 179 @}
 180 @end smallexample
 181
 182 @cindex preprocessor conditionals in templates
 183 @cindex conditionals (preprocessor) in templates
 184 @item
 185 A parsing bug makes it difficult to use preprocessor conditionals within
 186 templates.  For example, in this code:
 187
 188 @smallexample
 189 template <class T>
 190 class list @{
 191   @dots{}
 192 #ifdef SYSWRONG
 193   T x;
 194 #endif
 195   @dots{}
 196 @}
 197 @end smallexample
 198
 199 The preprocessor output leaves sourcefile line number information (lines
 200 like @samp{# 6 "foo.cc"} when it expands the @code{#ifdef} block.  These
 201 lines confuse the compiler while parsing templates, giving a syntax
 202 error.
 203
 204 If you cannot avoid preprocessor conditionals in templates, you can
 205 suppress the line number information using the @samp{-P} preprocessor
 206 option (but this will make debugging more difficult), by compiling the
 207 affected modules like this:
 208
 209 @smallexample
 210 g++ -P foo.cc -o foo
 211 @end smallexample
 212
 213 @cindex parsing errors, templates
 214 @item
 215 Parsing errors are reported when templates are first
 216 @emph{instantiated}---not on the template definition itself.  In
 217 particular, if you do not instantiate a template definition at all, the
 218 compiler never reports any parsing errors that may be in the template
 219 definition.
 220 @end itemize
 221
 222 @node Template debugging
 223 @section Debugging information for templates
 224
 225 @cindex templates and debugging information
 226 @cindex debugging information and templates
 227 Debugging information for templates works for some object code formats,
 228 but not others.  It works for stabs@footnote{Except that insufficient
 229 debugging information for methods of template classes is generated in
 230 stabs.} (used primarily in @sc{a.out} object code, but also in the Solaris 2
 231 version of @sc{elf}), and the @sc{mips} version of @sc{coff} debugging
 232 format.
 233
 234 @sc{dwarf} support is currently minimal, and requires further
 235 development.