@database templates.guide

@Master templates.texi

@Width 72


This is the AmigaGuide. file templates.guide, produced by Makeinfo-1.55 from 
the input file templates.texi.


@Node Main "templates.guide"

The Template Implementation
***************************

   The C++ template(1) facility, which effectively allows use of
variables for types in declarations, is one of the newest features of
the language.

   GNU C++ is one of the first compilers to implement many of the
template facilities currently defined by the ANSI committee.

   Nevertheless, the template implementation is not yet complete.  This
chapter maps the current limitations of the GNU C++ template
implementation.


 @{" Template limitations " Link "Template limitations"}  Limitations for function and class templates
 @{" Function templates " Link "Function templates"}    Limitations for function templates
 @{" Class templates " Link "Class templates"}       Limitations for class templates
 @{" Template debugging " Link "Template debugging"}    Debugging information for templates

   ---------- Footnotes ----------

   (1)  Class templates are also known as "parameterized types".


@EndNode

@Node "Template limitations" "templates.guide/Template limitations"
@Next "Function templates"
@Toc "Templates"

Limitations for function and class templates
============================================

   These limitations apply to any use of templates (function templates
or class templates) with GNU C++:

*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.

*Individual initializers needed for static data*
     Templates for static data in template classes do not work.  See
     @{"Limitations for class templates" Link "Class templates"}.


@EndNode

@Node "Function templates" "templates.guide/Function templates"
@Next "Class templates"
@Prev "Template limitations"
@Toc "Templates"

Limitations for function templates
==================================

   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.

The following limitations remain:

   * Narrowed specification: function declarations should not prevent
     template expansion.  When you declare a function, GNU C++
     interprets the declaration as an indication that you will provide a
     definition for that function.  Therefore, GNU C++ does not use a
     template expansion if there is also an applicable declaration.  GNU
     C++ only expands the template when there is no such declaration.

     The specification in Bjarne Stroustrup's `The C++ Programming
     Language, Second Edition' is narrower, and the 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:

          template <class X> X min (X& x1, X& x2) { ... }
          int min (int, int);
          ...
          int i; short s;
          min (i, s); // should call min(int,int)
                      // derived from template
          ...

   * 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
     `)' of the definition of the function `f':

          template <class T> class A { public: T x; class Y {}; };
          template <class X> int f (A<X>::Y y) { ... }

   * If you declare an `inline' function using templates, the compiler
     can only inline the code *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 GNU C++; the limitation will probably remain until
     the more general problem of nested functions is solved.

   * All the *method* templates (templates for member functions) for a
     class must be visible to the compiler when the class template is
     instantiated.


@EndNode

@Node "Class templates" "templates.guide/Class templates"
@Next "Template debugging"
@Prev "Function templates"
@Toc "Templates"

Limitations for class templates
===============================

     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.

   * Member functions in template classes may not have results of nested
     type; GNU C++ signals a syntax error on the attempt.  The following
     example illustrates this problem with an `enum' type `alph':

          template <class T> class list {
            ...
            enum alph {a,b,c};
            alph bar();
            ...
          };
          
          template <class T>
          list<int>::alph list<int>::bar()  // Syntax error here
          {
          ...
          }

   * A parsing bug makes it difficult to use preprocessor conditionals
     within templates.  For example, in this code:

          template <class T>
          class list {
            ...
          #ifdef SYSWRONG
            T x;
          #endif
            ...
          }

     The preprocessor output leaves sourcefile line number information
     (lines like `# 6 "foo.cc"' when it expands the `#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 `-P' preprocessor
     option (but this will make debugging more difficult), by compiling
     the affected modules like this:

          g++ -P foo.cc -o foo

   * Parsing errors are reported when templates are first
     *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.


@EndNode

@Node "Template debugging" "templates.guide/Template debugging"
@Prev "Class templates"
@Toc "Templates"

Debugging information for templates
===================================

   Debugging information for templates works for some object code
formats, but not others.  It works for stabs(1) (used primarily in
A.OUT object code, but also in the Solaris 2 version of ELF), and the
MIPS version of COFF debugging format.

   DWARF support is currently minimal, and requires further development.

   ---------- Footnotes ----------

   (1)  Except that insufficient debugging information for methods of
template classes is generated in stabs.

@EndNode