diff options
Diffstat (limited to 'gnu/usr.bin/cc/doc/templates.texi')
-rw-r--r-- | gnu/usr.bin/cc/doc/templates.texi | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/gnu/usr.bin/cc/doc/templates.texi b/gnu/usr.bin/cc/doc/templates.texi new file mode 100644 index 0000000..2a6db07 --- /dev/null +++ b/gnu/usr.bin/cc/doc/templates.texi @@ -0,0 +1,235 @@ +@node Templates +@chapter The Template Implementation + +@cindex templates +@cindex function templates +@cindex class templates +@cindex parameterized types +@cindex types, parameterized +The C++ template@footnote{Class templates are also known as +@dfn{parameterized types}.} facility, which effectively allows use of +variables for types in declarations, is one of the newest features of +the language. + +@sc{gnu} C++ is one of the first compilers to implement many +of the template facilities currently defined by the @sc{ansi} committee. + +Nevertheless, the template implementation is not yet complete. This +chapter maps the current limitations of the @sc{gnu} C++ template +implementation. + +@menu +* Template limitations:: Limitations for function and class templates +* Function templates:: Limitations for function templates +* Class templates:: Limitations for class templates +* Template debugging:: Debugging information for templates +@end menu + +@node Template limitations +@section Limitations for function and class templates + +@cindex template limitations +@cindex template bugs +@cindex bugs, templates +These limitations apply to any use of templates (function templates or +class templates) with @sc{gnu} C++: + +@table @emph +@item Template definitions must be visible +When you compile code with templates, the template definitions must come +first (before the compiler needs to expand them), and template +definitions you use must be visible in the current scope. +@c FIXME! Is this a defined property of templates, rather than a +@c temporary limitation? +@c ANSWER: It's a limitation, but it's hard to say why it's a limitation +@c to someone. We need an infinite link-cycle, in one camp, to +@c accomplish things so you don't need the template definitions around. + +@cindex static data in template classes +@cindex template classes, static data in +@item Individual initializers needed for static data +Templates for static data in template classes do not work. @xref{Class +templates,,Limitations for class templates}. +@end table + +@node Function templates +@section Limitations for function templates + +@cindex function template limitations +Function templates are implemented for the most part. The compiler can +correctly determine template parameter values, and will delay +instantiation of a function that uses templates until the requisite type +information is available. + +@noindent +The following limitations remain: + +@itemize @bullet +@cindex template vs declaration, functions +@cindex declaration vs template, functions +@cindex function declaration vs template +@item +Narrowed specification: function declarations should not prevent +template expansion. When you declare a function, @sc{gnu} C++ +interprets the declaration as an indication that you will provide a +definition for that function. Therefore, @sc{gnu} C++ does not use a +template expansion if there is also an applicable declaration. @sc{gnu} +C++ only expands the template when there is no such declaration. + +The specification in Bjarne Stroustrup's @cite{The C++ Programming +Language, Second Edition} is narrower, and the @sc{gnu} C++ +implementation is now clearly incorrect. With this new specification, a +declaration that corresponds to an instantiation of a function template +only affects whether conversions are needed to use that version of the +function. It should no longer prevent expansion of the template +definition. + +For example, this code fragment must be treated differently: + +@smallexample +template <class X> X min (X& x1, X& x2) @{ @dots{} @} +int min (int, int); +@dots{} +int i; short s; +min (i, s); // @r{should call} min(int,int) + // @r{derived from template} +@dots{} +@end smallexample + +@item +The compiler does not yet understand function signatures where types are +nested within template parameters. For example, a function like the +following produces a syntax error on the closing @samp{)} of the +definition of the function @code{f}: + +@smallexample +template <class T> class A @{ public: T x; class Y @{@}; @}; +template <class X> int f (A<X>::Y y) @{ @dots{} @} +@end smallexample + +@cindex @code{inline} and function templates +@cindex function templates and @code{inline} +@item +If you declare an @code{inline} function using templates, the compiler +can only inline the code @emph{after} the first time you use +that function with whatever particular type signature the template +was instantiated. + +Removing this limitation is akin to supporting nested function +definitions in @sc{gnu} C++; the limitation will probably remain until the +more general problem of nested functions is solved. + +@item +All the @emph{method} templates (templates for member functions) for a +class must be visible to the compiler when the class template is +instantiated. +@end itemize + +@node Class templates +@section Limitations for class templates + +@cindex class template limitations +@ignore +FIXME!! Include a comprehensible version of this if someone can explain it. + (Queried Brendan and Raeburn w/full orig context, 26may1993---pesch) + - [RHP: I don't understand what the following fragment refers to. If it's + the "BIG BUG" section in the original, why does it say "overriding class + declarations" here when the more detailed text refers to *function* + declarations? Here's the fragment I don't understand:] + there are problems with user-supplied overriding class declarations (see + below). +@end ignore + +@itemize @bullet +@ignore +@cindex static data, not working in templates +@item +Templates for static data in template classes do not work. +Currently, you must initialize each case of such data +individually. +@c FIXME!! Brendan to see if still true. +@c ANSWER: This section presumes that it's incorrect to have to +@c initialize for each type you instantiate with. It's not, it's the +@c right way to do it. +@end ignore + +Unfortunately, individual initializations of this sort are likely to be +considered errors eventually; since they're needed now, you might want to +flag places where you use them with comments to mark the need for a +future transition. + +@cindex nested type results vs templates +@item +Member functions in template classes may not have results of nested +type; @sc{gnu} C++ signals a syntax error on the attempt. The following +example illustrates this problem with an @code{enum} type @code{alph}: + +@smallexample +template <class T> class list @{ + @dots{} + enum alph @{a,b,c@}; + alph bar(); + @dots{} +@}; + +template <class T> +list<int>::alph list<int>::bar() // @i{Syntax error here} +@{ +@dots{} +@} +@end smallexample + +@cindex preprocessor conditionals in templates +@cindex conditionals (preprocessor) in templates +@item +A parsing bug makes it difficult to use preprocessor conditionals within +templates. For example, in this code: + +@smallexample +template <class T> +class list @{ + @dots{} +#ifdef SYSWRONG + T x; +#endif + @dots{} +@} +@end smallexample + +The preprocessor output leaves sourcefile line number information (lines +like @samp{# 6 "foo.cc"} when it expands the @code{#ifdef} block. These +lines confuse the compiler while parsing templates, giving a syntax +error. + +If you cannot avoid preprocessor conditionals in templates, you can +suppress the line number information using the @samp{-P} preprocessor +option (but this will make debugging more difficult), by compiling the +affected modules like this: + +@smallexample +g++ -P foo.cc -o foo +@end smallexample + +@cindex parsing errors, templates +@item +Parsing errors are reported when templates are first +@emph{instantiated}---not on the template definition itself. In +particular, if you do not instantiate a template definition at all, the +compiler never reports any parsing errors that may be in the template +definition. +@end itemize + +@node Template debugging +@section Debugging information for templates + +@cindex templates and debugging information +@cindex debugging information and templates +Debugging information for templates works for some object code formats, +but not others. It works for stabs@footnote{Except that insufficient +debugging information for methods of template classes is generated in +stabs.} (used primarily in @sc{a.out} object code, but also in the Solaris 2 +version of @sc{elf}), and the @sc{mips} version of @sc{coff} debugging +format. + +@sc{dwarf} support is currently minimal, and requires further +development. |