Ada Reference Manual (Ada 2022) — Legal Information

# 12.3 Generic Instantiation

1
An instance of a generic unit is declared by a generic_instantiation.

#### Syntax

2/3
generic_instantiation ::=
package defining_program_unit_name is
new generic_package_name [generic_actual_part]
[aspect_specification];
| [overriding_indicator]
procedure defining_program_unit_name is
new generic_procedure_name [generic_actual_part]
[aspect_specification];
| [overriding_indicator]
function defining_designator is
new generic_function_name [generic_actual_part]
[aspect_specification];
3
generic_actual_part ::=
(generic_association {, generic_association})
4
generic_association ::=
[generic_formal_parameter_selector_name =>] explicit_generic_actual_parameter
5
explicit_generic_actual_parameter ::= expression | variable_name
| subprogram_name | entry_name | subtype_mark
| package_instance_name
6
A generic_association is named or positional according to whether or not the generic_formal_parameter_selector_name is specified. Any positional associations shall precede any named associations.
7/5
The generic actual parameter is either the explicit_generic_actual_parameter given in a generic_association for each formal, or the corresponding default_expression, default_subtype_mark, or default_name if no generic_association is given for the formal. When the meaning is clear from context, the term “generic actual”, or simply “actual”, is used as a synonym for “generic actual parameter” and also for the view denoted by one, or the value of one.

#### Legality Rules

8
In a generic_instantiation for a particular kind of program unit (package, procedure, or function), the name shall denote a generic unit of the corresponding kind (generic package, generic procedure, or generic function, respectively).
9/3
The generic_formal_parameter_selector_name of a named generic_association shall denote a generic_formal_parameter_declaration of the generic unit being instantiated. If two or more formal subprograms have the same defining name, then named associations are not allowed for the corresponding actuals.
9.1/3
The generic_formal_parameter_declaration for a positional generic_association is the parameter with the corresponding position in the generic_formal_part of the generic unit being instantiated.
10/5
A generic_instantiation shall contain at most one generic_association for each formal. Each formal without an association shall have a default_expression, default_subtype_mark, or subprogram_default.
11/5
In a generic unit, Legality Rules are enforced at compile time of the generic_declaration and generic body, given the properties of the formals. In the visible part and formal part of an instance, Legality Rules are enforced at compile time of the generic_instantiation, given the properties of the actuals. In other parts of an instance, Legality Rules are not enforced; this rule does not apply when a given rule explicitly specifies otherwise.

#### Static Semantics

12
A generic_instantiation declares an instance; it is equivalent to the instance declaration (a package_declaration or subprogram_declaration) immediately followed by the instance body, both at the place of the instantiation.
13
The instance is a copy of the text of the template. Each use of a formal parameter becomes (in the copy) a use of the actual, as explained below. An instance of a generic package is a package, that of a generic procedure is a procedure, and that of a generic function is a function.
14
The interpretation of each construct within a generic declaration or body is determined using the overloading rules when that generic declaration or body is compiled. In an instance, the interpretation of each (copied) construct is the same, except in the case of a name that denotes the generic_declaration or some declaration within the generic unit; the corresponding name in the instance then denotes the corresponding copy of the denoted declaration. The overloading rules do not apply in the instance.
15/5
In an instance, a generic_formal_parameter_declaration declares a view whose properties are identical to those of the actual, except when specified otherwise (in particular, see 6.1.1, “Preconditions and Postconditions”, 12.4, “Formal Objects”, and 12.6, “Formal Subprograms”). Similarly, for a declaration within a generic_formal_parameter_declaration, the corresponding declaration in an instance declares a view whose properties are identical to the corresponding declaration within the declaration of the actual.
16
Implicit declarations are also copied, and a name that denotes an implicit declaration in the generic denotes the corresponding copy in the instance. However, for a type declared within the visible part of the generic, a whole new set of primitive subprograms is implicitly declared for use outside the instance, and may differ from the copied set if the properties of the type in some way depend on the properties of some actual type specified in the instantiation. For example, if the type in the generic is derived from a formal private type, then in the instance the type will inherit subprograms from the corresponding actual type.
17
These new implicit declarations occur immediately after the type declaration in the instance, and override the copied ones. The copied ones can be called only from within the instance; the new ones can be called only from outside the instance, although for tagged types, the body of a new one can be executed by a call to an old one.
18
In the visible part of an instance, an explicit declaration overrides an implicit declaration if they are homographs, as described in 8.3. On the other hand, an explicit declaration in the private part of an instance overrides an implicit declaration in the instance, only if the corresponding explicit declaration in the generic overrides a corresponding implicit declaration in the generic. Corresponding rules apply to the other kinds of overriding described in 8.3.

#### Post-Compilation Rules

19
Recursive generic instantiation is not allowed in the following sense: if a given generic unit includes an instantiation of a second generic unit, then the instance generated by this instantiation shall not include an instance of the first generic unit (whether this instance is generated directly, or indirectly by intermediate instantiations).

#### Dynamic Semantics

20
For the elaboration of a generic_instantiation, each generic_association is first evaluated. If a default is used, an implicit generic_association is assumed for this rule. These evaluations are done in an arbitrary order, except that the evaluation for a default actual takes place after the evaluation for another actual if the default includes a name that denotes the other one. Finally, the instance declaration and body are elaborated.
21
For the evaluation of a generic_association the generic actual parameter is evaluated. Additional actions are performed in the case of a formal object of mode in (see 12.4).
22
NOTE If a formal type is not tagged, then the type is treated as an untagged type within the generic body. Deriving from such a type in a generic body is permitted; the new type does not get a new tag value, even if the actual is tagged. Overriding operations for such a derived type cannot be dispatched to from outside the instance.

#### Examples

23
Examples of generic instantiations (see 12.1):
24/5
procedure Swap is new Exchange(Elem => Integer);
procedure Swap is new Exchange(Character); -- Swap is overloaded
function Square is new Squaring(Integer); -- "*" of Integer used by default
function Square1 is new Squaring(Item => Matrix, "*" => Matrix_Product);
function Square2 is new Squaring(Matrix, Matrix_Product); -- same as previous
25
package Int_Vectors is new On_Vectors(Integer, Table, "+");
26
Examples of uses of instantiated units:
27
Swap(A, B);
A := Square(A);
28
T : Table(1 .. 5) := (10, 20, 30, 40, 50);
N : Integer := Int_Vectors.Sigma(T); -- 150
-- (see 12.2 for the body of Sigma)
29
use Int_Vectors;
M : Integer := Sigma(T); -- 150

Ada 2005 and 2012 Editions sponsored in part by Ada-Europe