Template Definition and Scope

To use a template, its full definition, not merely its declaration, must be in scope.

Programming

Why a Container Needs a Template

Suppose your program needs a container that holds a list of numbers. The C++ standard library offers a ready-made option called vector. Vector is a template: a single description that the compiler can turn into a concrete container for whatever element type you ask for. A vector of integers and a vector of strings both come from the same description.

Using a template is not as simple as calling a function whose signature you already know. To produce the specialized code you need for your element type, the compiler has to be able to see the full template. This requirement is often called the scope requirement for templates. It is the subject of this article, along with the trouble it can cause when something goes wrong.

Hold this question in mind as you read: when your code says it wants a vector of some element type, what must the compiler be able to see at that exact point?

Declaration Versus Definition

Two terms need to be kept apart. A declaration tells the compiler that something exists and describes its shape. A definition supplies the complete body that goes with that shape. For ordinary functions and classes, you may often see a declaration in one place and a definition in another, and the program still works as long as the compiler has what it needs.

The declaration says the template exists and describes its shape; only the full definition supplies the body the compiler needs to generate code for a specific element type.

For templates, this distinction carries real weight. A declaration by itself is not enough to use the template. What the compiler needs is the full template, meaning the complete definition, visible where the template is used.

How a Header Brings a Template Into Scope

The standard header <vector> holds the definition of vector. When your program includes that header, the full definition of the template becomes available to the compiler, and you can then use vector with your own element types. The header is therefore not just a name tag. It carries the complete template that the compiler needs.

cpp

#include <vector>

int main() {
    std::vector<int> scores;
    scores.push_back(90);
    return 0;
}

#include <vector>

int main() {
    std::vector<int> scores;
    scores.push_back(90);
    return 0;
}

Notes on the code

#include <vector> brings the full vector template definition into the source file being compiled
std::vector<int> asks the compiler to produce a container specialized for int elements
The use site relies on the template definition being in scope at this point

Including <vector> makes the full std::vector template definition available, so the program can use vector with its own element types.

Following a Use Site Through the Compiler

Trace what happens when your code names a template use. The compiler sees the place where vector is used along with the element type supplied there. To produce the specialized code for that element type, it needs the full template. The source describes this as the compiler needing to see the full template in order to produce the specialized code you need.

A template use is checked against the full definition in scope; when that definition is available, the compiler can produce specialized code, and when it is not, the use cannot be turned into code.

Use this pipeline as a mental model rather than a literal list of compiler stages. The key point is that the full definition must be available where the template is used, and that is the requirement the header exists to satisfy.

Late Errors in Template Code

The scope requirement has an unfortunate side effect. A type error involving a template can be detected uncomfortably late in compilation. The compiler discovers the problem only after it combines information from several places: the template definition, the place where it is used, and the types supplied at that use.

Because the mistake depends on how these pieces fit together, the compiler cannot always report it at the moment a programmer might first expect. The error can therefore appear far from the line where the template was written. Late template errors can also produce poor error messages. The practical advice from the source is to read them carefully and trace back to the use that caused them.

Mistakes Beginners Make with Template Scope

Common mistake
Assuming a declaration alone is enough to use a template
Why it fails
A declaration says the template exists and describes its shape, but the compiler needs the full definition to produce specialized code.
Do this instead
Make sure the full definition is in scope at the point of use, for example by including the standard header that provides it.
Common mistake
Treating <vector> as only a name tag
Why it fails
The header carries the complete template, so including it is what makes vector usable with your element types.
Do this instead
Include <vector> when you need std::vector, and understand that the include supplies the definition.
Common mistake
Reading a late template error as a problem at the line where the error appears
Why it fails
The compiler combines the template definition, the use site, and the supplied types, so the reported location may be far from the actual cause.
Do this instead
Read the error carefully and trace back to the template use that triggered it.

Checking Your Understanding

EASY

Your program uses std::vector to store exam scores, but the code fails to compile because the compiler cannot see the template's full definition. Which standard header should you include, and why does including it help?

Hints

Recall which standard header the source names as holding the definition of vector.
Think about what the compiler needs at the point of use, not just what it needs to know that vector exists.

Your attempt (not saved)

What do you think happens?

If a template use can only see the declaration, and not the full definition, can the compiler produce the specialized code for that use?

Reveal answer

Answer:

No. The compiler needs the full template definition in scope to produce the specialized code.

A declaration says the template exists and describes its shape, but the complete body is what the compiler needs to generate the code for a specific element type.

Key Takeaways

A template's full definition, not merely its declaration, must be in scope before the template can be used.
A declaration says something exists and describes its shape, while a definition supplies the complete body the compiler needs.
The standard header <vector> holds the definition of vector, so including it makes that template available for your own element types.
Template type errors can surface late because the compiler combines the template definition, the use site, and the supplied types, so messages may be hard to read and should be traced back to the use that caused them.

Related concepts

More concepts starting with T