5.2 Template Definitions

You can organize your template definitions in two ways: with definitions included and with definitions separated. The definitions-included organization allows greater control over template compilation.

5.2.1 Template Definitions Included

When you put the declarations and definitions for a template within the file that uses the template, the organization is definitions-included. For example:

main.cc

template <class Number> Number twice(Number original);
template <class Number> Number twice(Number original )
    { return original + original; }
int main()
    { return twice<int>(-3); }

When a file using a template includes a file that contains both the template’s declaration and the template’s definition, the file that uses the template also has the definitions-included organization. For example:

twice.h

#ifndef TWICE_H
#define TWICE_H
template <class Number>
Number twice(Number original);
template <class Number> Number twice( Number original )
    { return original + original; }
#endif

main.cc

#include “twice.h”
int main()
    { return twice(-3); }

5.2.2 Template Definitions Separate

Another way to organize template definitions is to keep the definitions in template definition files, as shown in the following example.

twice.h

#ifndef TWICE_H
#define TWICE_H
template <class Number>
Number twice(Number original);
#endif TWICE_H

twice.cc

template <class Number>
Number twice( Number original )
    { return original + original; }

main.cc

#include “twice.h”
int main( )
    { return twice<int>( -3 ); }

Template definition files must not include any non-idempotent header files and often need not include any header files at all. (See 5.1.2 Idempotent Header Files.) Note that not all compilers support the definitions-separate model for templates.

Because a separate definitions file is a header file, it might be included implicitly in many files. It therefore should not contain any function or variable definitions, unless they are part of a template definition. A separate definitions file can include type definitions, including typedefs.

If you place template declarations in one file and template definitions in another file, you have to be very careful how you construct the definition file, what you name it, and where you put it. You might also need to identify explicitly to the compiler the location of the definitions. Refer to 7.5 Template Definition Searching” for information about the template definition search rules.

When generating preprocessor output with the -E or -P options, the definitions-separate file organization does not allow the template definitions to be included in the .i file. Compiling the .i file can fail due to missing definitions. By conditionally including the template definition file in the template declaration header (see code example below), you can ensure the template definitions are available by using -template=no%extdef on the command line. The libCtd and STLport libraries are implemented in this way.

// templace declaration file
template <class T> class foo { ... };
#ifdef _TEMPLATE_NO_EXTDEF
#include "foo.cc"  //template definition file
#endif

However, do not attempt to define the macro _TEMPLATE_NO_EXTDEF yourself. When defined without the —template=no%extdef option, you can get compilation failures due to multiple inclusion of template definition files.