2 @chapter The Template Implementation
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
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.
17 Nevertheless, the template implementation is not yet complete. This
18 chapter maps the current limitations of the @sc{gnu} C++ template
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
28 @node Template limitations
29 @section Limitations for function and class templates
31 @cindex template limitations
33 @cindex bugs, templates
34 These limitations apply to any use of templates (function templates or
35 class templates) with @sc{gnu} C++:
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.
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}.
55 @node Function templates
56 @section Limitations for function templates
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.
65 The following limitations remain:
68 @cindex template vs declaration, functions
69 @cindex declaration vs template, functions
70 @cindex function declaration vs template
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.
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
87 For example, this code fragment must be treated differently:
90 template <class X> X min (X& x1, X& x2) @{ @dots{} @}
94 min (i, s); // @r{should call} min(int,int)
95 // @r{derived from template}
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}:
106 template <class T> class A @{ public: T x; class Y @{@}; @};
107 template <class X> int f (A<X>::Y y) @{ @dots{} @}
110 @cindex @code{inline} and function templates
111 @cindex function templates and @code{inline}
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
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.
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
128 @node Class templates
129 @section Limitations for class templates
131 @cindex class template limitations
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
145 @cindex static data, not working in templates
147 Templates for static data in template classes do not work.
148 Currently, you must initialize each case of such data
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.
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
161 @cindex nested type results vs templates
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}:
168 template <class T> class list @{
176 list<int>::alph list<int>::bar() // @i{Syntax error here}
182 @cindex preprocessor conditionals in templates
183 @cindex conditionals (preprocessor) in templates
185 A parsing bug makes it difficult to use preprocessor conditionals within
186 templates. For example, in this code:
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
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:
213 @cindex parsing errors, templates
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
222 @node Template debugging
223 @section Debugging information for templates
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
234 @sc{dwarf} support is currently minimal, and requires further