Templates

Each instantiation of a templated class must be wrapped separately. There are two ways to specify which instantiations to wrap i.e. listing them manually or discovering them from the source (or a combination of both).

template_substitutions

Manually list instantiations as a signature with a list of replacement argument lists:

modules:
  - name: mesh
    classes:
      - name: AbstractMesh
        template_substitutions:
          - signature: <unsigned ELEMENT_DIM, unsigned SPACE_DIM>
            replacement: [[2, 2], [3, 3]]

The configuration above wraps:

AbstractMesh<2, 2>
AbstractMesh<3, 3>

Note

Each replacement must have one value per template parameter in the signature.

discover_template_instantiations

With discover_template_instantiations: True, cppwg automatically scans the .cpp source files to find explicit instantiations:

discover_template_instantiations: True   # package level: applies to all classes
modules:
  - name: mesh
    classes:
      - name: AbstractMesh

Given the explicit instantiations below in the .cpp sources, the configuration above wraps AbstractMesh<2, 2> and AbstractMesh<3, 3>, the same result as the template_substitutions example above, without listing them by hand:

template class AbstractMesh<2, 2>;
template class AbstractMesh<3, 3>;

Discovery reads literal template class statements directly via text parsing and falls back to CastXML when all instantiations are macro-generated. A file that mixes literal and macro-generated instantiations is not fully discovered and must be configured manually with template_substitutions.

Caution

Recovering a defaulted trailing template argument (such as <unsigned T, unsigned U=T>) consistently from an explicit instantiation declared via a macro requires CastXML >= 0.6.0. See the MacroMesh class in examples/cells for an example.

discover_arg_excludes

To filter out specific instantiations during automatic discovery, map a template-parameter name to the argument values to drop:

discover_arg_excludes:
  DIM: [0]
  ELEMENT_DIM: [0]
  SPACE_DIM: [0]

The configuration above drops any discovered instantiation that binds DIM, ELEMENT_DIM, or SPACE_DIM to 0, while keeping e.g. Foo<SPACE_DIM=1>.

Matching is by parameter name, so a 0 bound to a parameter that is not listed survives. For example, with the signature <unsigned SPACE_DIM, unsigned ELEMENT_DIM, unsigned PROBLEM_DIM>, the instantiation Bar<1, 1, 0> is kept as its trailing 0 is bound to PROBLEM_DIM, which is not in the map. Only discovered instantiations are filtered; template_substitutions are always wrapped as written.

Note

A key may be the bare parameter name (ELEMENT_DIM) or carry a leading type (unsigned ELEMENT_DIM).

Auto-excluded instantiations

cppwg automatically drops a discovered instantiation whose wrapped methods take or return a template type that is never instantiated. These would otherwise fail to link or import with an undefined symbol further downstream. See Corner and Facet in examples/cells.

See also

See Reference for a list of all configuration options.