Return to templates.texi CVS log

Up to [GCC 2.x] / gcc / cp

Annotation of gcc/cp/templates.texi, revision 1.1

1.1     ! root        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.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.