12 Generic Units 1 A generic unit is a program unit that is either a generic subprogram or a generic package. A generic unit is a template[, which can be parameterized, and from which corresponding (nongeneric) subprograms or packages can be obtained]. The resulting program units are said to be instances of the original generic unit. 1.a Glossary entry: A generic unit is a template for a (nongeneric) program unit; the template can be parameterized by objects, types, subprograms, and packages. An instance of a generic unit is created by a generic_instantiation. The rules of the language are enforced when a generic unit is compiled, using a generic contract model; additional checks are performed upon instantiation to verify the contract is met. That is, the declaration of a generic unit represents a contract between the body of the generic and instances of the generic. Generic units can be used to perform the role that macros sometimes play in other languages. 2 [A generic unit is declared by a generic_declaration. This form of declaration has a generic_formal_part declaring any generic formal parameters. An instance of a generic unit is obtained as the result of a generic_instantiation with appropriate generic actual parameters for the generic formal parameters. An instance of a generic subprogram is a subprogram. An instance of a generic package is a package. 3 Generic units are templates. As templates they do not have the properties that are specific to their nongeneric counterparts. For example, a generic subprogram can be instantiated but it cannot be called. In contrast, an instance of a generic subprogram is a (nongeneric) subprogram; hence, this instance can be called but it cannot be used to produce further instances.] 12.1 Generic Declarations 1 [A generic_declaration declares a generic unit, which is either a generic subprogram or a generic package. A generic_declaration includes a generic_formal_part declaring any generic formal parameters. A generic formal parameter can be an object; alternatively (unlike a parameter of a subprogram), it can be a type, a subprogram, or a package.] Syntax 2 generic_declaration ::= generic_subprogram_declaration | generic_package_declaration 3/3 {AI05-0183-1} generic_subprogram_declaration ::= generic_formal_part subprogram_specification [aspect_specification]; 4 generic_package_declaration ::= generic_formal_part package_specification; 4.a/3 Ramification: {AI05-0183-1} No syntax change is needed here to allow an aspect_specification; a generic package can have an aspect_specification because a package_specification allows an aspect_specification. 5 generic_formal_part ::= generic {generic_formal_parameter_declaration | use_clause} 6 generic_formal_parameter_declaration ::= formal_object_declaration | formal_type_declaration | formal_subprogram_declaration | formal_package_declaration 7 The only form of subtype_indication allowed within a generic_formal_part is a subtype_mark [(that is, the subtype_indication shall not include an explicit constraint)]. The defining name of a generic subprogram shall be an identifier [(not an operator_symbol)]. 7.a Reason: The reason for forbidding constraints in subtype_indications is that it simplifies the elaboration of generic_declarations (since there is nothing to evaluate), and that it simplifies the matching rules, and makes them more checkable at compile time. Static Semantics 8/2 {AI95-00434-01} A generic_declaration declares a generic unit - a generic package, generic procedure, or generic function, as appropriate. 9 An entity is a generic formal entity if it is declared by a generic_formal_parameter_declaration. "Generic formal," or simply "formal," is used as a prefix in referring to objects, subtypes (and types), functions, procedures and packages, that are generic formal entities, as well as to their respective declarations. [Examples: "generic formal procedure" or a "formal integer type declaration."] Dynamic Semantics 10 The elaboration of a generic_declaration has no effect. NOTES 11 1 Outside a generic unit a name that denotes the generic_declaration denotes the generic unit. In contrast, within the declarative region of the generic unit, a name that denotes the generic_declaration denotes the current instance. 11.a Proof: This is stated officially as part of the "current instance" rule in 8.6, "The Context of Overload Resolution". See also 12.3, "Generic Instantiation". 12 2 Within a generic subprogram_body, the name of this program unit acts as the name of a subprogram. Hence this name can be overloaded, and it can appear in a recursive call of the current instance. For the same reason, this name cannot appear after the reserved word new in a (recursive) generic_instantiation. 13 3 A default_expression or default_name appearing in a generic_formal_part is not evaluated during elaboration of the generic_formal_part; instead, it is evaluated when used. (The usual visibility rules apply to any name used in a default: the denoted declaration therefore has to be visible at the place of the expression.) Examples 14 Examples of generic formal parts: 15 generic -- parameterless 16 generic Size : Natural; -- formal object 17 generic Length : Integer := 200; -- formal object with a default expression 18 Area : Integer := Length*Length; -- formal object with a default expression 19 generic type Item is private; -- formal type type Index is (<>); -- formal type type Row is array(Index range <>) of Item; -- formal type with function "<"(X, Y : Item) return Boolean; -- formal subprogram 20 Examples of generic declarations declaring generic subprograms Exchange and Squaring: 21 generic type Elem is private; procedure Exchange(U, V : in out Elem); 22 generic type Item is private; with function "*"(U, V : Item) return Item is <>; function Squaring(X : Item) return Item; 23 Example of a generic declaration declaring a generic package: 24 generic type Item is private; type Vector is array (Positive range <>) of Item; with function Sum(X, Y : Item) return Item; package On_Vectors is function Sum (A, B : Vector) return Vector; function Sigma(A : Vector) return Item; Length_Error : exception; end On_Vectors; Extensions to Ada 83 24.a The syntax rule for generic_formal_parameter_declaration is modified to allow the reserved words tagged and abstract, to allow formal derived types, and to allow formal packages. 24.b Use_clauses are allowed in generic_formal_parts. This is necessary in order to allow a use_clause within a formal part to provide direct visibility of declarations within a generic formal package. Wording Changes from Ada 83 24.c/3 {AI05-0299-1} The syntax for generic_formal_parameter_declaration and formal_type_definition is split up into more named categories. The rules for these categories are moved to the appropriate subclauses. The names of the categories are changed to be more intuitive and uniform. For example, we changed generic_parameter_declaration to generic_formal_parameter_declaration, because the thing it declares is a generic formal, not a generic. In the others, we abbreviate "generic_formal" to just "formal". We can't do that for generic_formal_parameter_declaration, because of confusion with normal formal parameters of subprograms. Extensions to Ada 2005 24.d/3 {AI05-0183-1} An optional aspect_specification can be used in a generic_subprogram_declaration (as well as a generic_package_declaration). This is described in 13.1.1. 12.2 Generic Bodies 1 The body of a generic unit (a generic body) [is a template for the instance bodies. The syntax of a generic body is identical to that of a nongeneric body]. 1.a Ramification: We also use terms like "generic function body" and "nongeneric package body." Dynamic Semantics 2 The elaboration of a generic body has no other effect than to establish that the generic unit can from then on be instantiated without failing the Elaboration_Check. If the generic body is a child of a generic package, then its elaboration establishes that each corresponding declaration nested in an instance of the parent (see 10.1.1) can from then on be instantiated without failing the Elaboration_Check. NOTES 3 4 The syntax of generic subprograms implies that a generic subprogram body is always the completion of a declaration. Examples 4 Example of a generic procedure body: 5 procedure Exchange(U, V : in out Elem) is -- see 12.1 T : Elem; -- the generic formal type begin T := U; U := V; V := T; end Exchange; 6 Example of a generic function body: 7 function Squaring(X : Item) return Item is -- see 12.1 begin return X*X; -- the formal operator "*" end Squaring; 8 Example of a generic package body: 9 package body On_Vectors is -- see 12.1 10 function Sum(A, B : Vector) return Vector is Result : Vector(A'Range); -- the formal type Vector Bias : constant Integer := B'First - A'First; begin if A'Length /= B'Length then raise Length_Error; end if; 11 for N in A'Range loop Result(N) := Sum(A(N), B(N + Bias)); -- the formal function Sum end loop; return Result; end Sum; 12 function Sigma(A : Vector) return Item is Total : Item := A(A'First); -- the formal type Item begin for N in A'First + 1 .. A'Last loop Total := Sum(Total, A(N)); -- the formal function Sum end loop; return Total; end Sigma; end On_Vectors; 12.3 Generic Instantiation 1 [ An instance of a generic unit is declared by a generic_instantiation.] Language Design Principles 1.a/3 {AI05-0299-1} The legality of an instance should be determinable without looking at the generic body. Likewise, the legality of a generic body should be determinable without looking at any instances. Thus, the generic_declaration forms a contract between the body and the instances; if each obeys the rules with respect to the generic_declaration, then no legality problems will arise. This is really a special case of the "legality determinable via semantic dependences" Language Design Principle (see Clause 10), given that a generic_instantiation does not depend semantically upon the generic body, nor vice-versa. 1.b Run-time issues are another story. For example, whether parameter passing is by copy or by reference is determined in part by the properties of the generic actuals, and thus cannot be determined at compile time of the generic body. Similarly, the contract model does not apply to Post-Compilation Rules. Syntax 2/3 {AI95-00218-03} {AI05-0183-1} 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/3 {AI05-0004-1} The generic actual parameter is either the explicit_generic_actual_parameter given in a generic_association for each formal, or the corresponding default_expression 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 {AI05-0118-1} 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 {AI05-0118-1} 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 A generic_instantiation shall contain at most one generic_association for each formal. Each formal without an association shall have a default_expression or subprogram_default. 11 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. 11.a/2 Reason: {AI95-00114-01} Since rules are checked using the properties of the formals, and since these properties do not always carry over to the actuals, we need to check the rules again in the visible part of the instance. For example, only if a tagged type is limited may an extension of it have limited components in the record_extension_part. A formal tagged limited type is limited, but the actual might be nonlimited. Hence any rule that requires a tagged type to be limited runs into this problem. Such rules are rare; in most cases, the rules for matching of formals and actuals guarantee that if the rule is obeyed in the generic unit, then it has to be obeyed in the instance. 11.a.1/3 {AI05-0005-1} Ada 2012 addendum: Such Legality Rules are not as rare as the authors of Ada 95 hoped; there are more than 30 of them known at this point. They are indexed under "generic contract issue" and are associated with the boilerplate "In addition to the places where Legality Rules normally apply...". Indeed, there is only one known rule where rechecking in the specification is needed and where rechecking in the private part is not wanted (it is in 3.4, but even it needs rechecking when tagged types are involved). 11.b Ramification: The "properties" of the formals are determined without knowing anything about the actuals: 11.c/1 * {8652/0095} {AI95-00034-01} A formal derived subtype is constrained if and only if the ancestor subtype is constrained. A formal array type is constrained if and only if the declarations say so. A formal private type is constrained if it does not have a discriminant part. Other formal subtypes are unconstrained, even though they might be constrained in an instance. 11.d * A formal subtype can be indefinite, even though the copy might be definite in an instance. 11.e * A formal object of mode in is not a static constant; in an instance, the copy is static if the actual is. 11.f * A formal subtype is not static, even though the actual might be. 11.g * Formal types are specific, even though the actual can be class-wide. 11.h * The subtype of a formal object of mode in out is not static. (This covers the case of AI83-00878.) 11.i * The subtype of a formal parameter of a formal subprogram does not provide an applicable index constraint. 11.j/3 * {AI05-0239-1} The profile of a formal subprogram is not subtype conformant with any other profile. 11.k * A generic formal function is not static. 11.l Ramification: The exceptions to the above rule about when legality rules are enforced fall into these categories: 11.m * Some rules are checked in the generic declaration, and then again in both the visible and private parts of the instance: 11.n * The parent type of a record extension has to be specific (see 3.9.1). This rule is not checked in the instance body. 11.o * The parent type of a private extension has to be specific (see 7.3). This rule is not checked in the instance body. 11.p/3 * {AI95-00402-01} {AI05-0093-1} A type with an access discriminant with a default_expression has to be immutably limited. In the generic body, the definition of immutably limited is adjusted in an assume-the-worst manner (thus the rule is checked that way). 11.q * In the declaration of a record extension, if the parent type is nonlimited, then each of the components of the record_extension_part have to be nonlimited (see 3.9.1). In the generic body, this rule is checked in an assume-the-worst manner. 11.r * A preelaborated library unit has to be preelaborable (see 10.2.1). In the generic body, this rule is checked in an assume-the-worst manner. 11.r.1/2 {AI95-00402-01} The corrections made by the Corrigendum added a number of such rules, and the Amendment added many more. There doesn't seem to be much value in repeating all of these rules here (as of this writing, there are roughly 33 such rules). As noted below, all such rules are indexed in the AARM. 11.s * For the accessibility rules, the formals have nothing to say about the property in question. Like the above rules, these rules are checked in the generic declaration, and then again in both the visible and private parts of the instance. In the generic body, we have explicit rules that essentially assume the worst (in the cases of type extensions and access-to-subprogram types), and we have run-time checks (in the case of access-to-object types). See 3.9.1, 3.10.2, and 4.6. 11.t We considered run-time checks for access-to-subprogram types as well. However, this would present difficulties for implementations that share generic bodies. 11.u * The rules requiring "reasonable" values for static expressions are ignored when the expected type for the expression is a descendant of a generic formal type other than a generic formal derived type, and do not apply in an instance. 11.v * The rule forbidding two explicit homographs in the same declarative region does not apply in an instance of a generic unit, except that it does apply in the declaration of a record extension that appears in the visible part of an instance. 11.w * Some rules do not apply at all in an instance, not even in the visible part: 11.x * Body_stubs are not normally allowed to be multiply nested, but they can be in instances. 11.y Each rule that is an exception is marked with "generic contract issue;" look that up in the index to find them all. 11.z Ramification: The Legality Rules are the ones labeled Legality Rules. We are talking about all Legality Rules in the entire language here. Note that, with some exceptions, the legality of a generic unit is checked even if there are no instantiations of the generic unit. 11.aa/3 Ramification: {AI05-0299-1} The Legality Rules are described here, and the overloading rules were described earlier in this subclause. Presumably, every Static Semantic Item is sucked in by one of those. Thus, we have covered all the compile-time rules of the language. There is no need to say anything special about the Post-Compilation Rules or the Dynamic Semantic Items. 11.bb Discussion: Here is an example illustrating how this rule is checked: "In the declaration of a record extension, if the parent type is nonlimited, then each of the components of the record_extension_part shall be nonlimited." 11.cc generic type Parent is tagged private; type Comp is limited private; package G1 is type Extension is new Parent with record C : Comp; -- Illegal! end record; end G1; 11.dd/1 The parent type is nonlimited, and the component type is limited, which is illegal. It doesn't matter that one could imagine writing an instantiation with the actual for Comp being nonlimited - we never get to the instance, because the generic itself is illegal. 11.ee On the other hand: 11.ff generic type Parent is tagged limited private; -- Parent is limited. type Comp is limited private; package G2 is type Extension is new Parent with record C : Comp; -- OK. end record; end G2; 11.gg type Limited_Tagged is tagged limited null record; type Non_Limited_Tagged is tagged null record; 11.hh type Limited_Untagged is limited null record; type Non_Limited_Untagged is null record; 11.ii package Good_1 is new G2(Parent => Limited_Tagged, Comp => Limited_Untagged); package Good_2 is new G2(Parent => Non_Limited_Tagged, Comp => Non_Limited_Untagged); package Bad is new G2(Parent => Non_Limited_Tagged, Comp => Limited_Untagged); -- Illegal! 11.jj The first instantiation is legal, because in the instance the parent is limited, so the rule is not violated. Likewise, in the second instantiation, the rule is not violated in the instance. However, in the Bad instance, the parent type is nonlimited, and the component type is limited, so this instantiation is illegal. 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. 12.a Ramification: The declaration and the body of the instance are not "implicit" in the technical sense, even though you can't see them in the program text. Nor are declarations within an instance " implicit" (unless they are implicit by other rules). This is necessary because implicit declarations have special semantics that should not be attached to instances. For a generic subprogram, the profile of a generic_instantiation is that of the instance declaration, by the stated equivalence. 12.b Ramification: The visible and private parts of a package instance are defined in 7.1, "Package Specifications and Declarations" and 12.7, "Formal Packages". The visible and private parts of a subprogram instance are defined in 8.2, "Scope of Declarations". 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. 13.a Ramification: An instance is a package or subprogram (because we say so), even though it contains a copy of the generic_formal_part, and therefore doesn't look like one. This is strange, but it's OK, since the syntax rules are overloading rules, and therefore do not apply in an instance. 13.b Discussion: We use a macro-expansion model, with some explicitly-stated exceptions (see below). The main exception is that the interpretation of each construct in a generic unit (especially including the denotation of each name) is determined when the declaration and body of the generic unit (as opposed to the instance) are compiled, and in each instance this interpretation is (a copy of) the template interpretation. In other words, if a construct is interpreted as a name denoting a declaration D, then in an instance, the copy of the construct will still be a name, and will still denote D (or a copy of D). From an implementation point of view, overload resolution is performed on the template, and not on each copy. 13.c We describe the substitution of generic actual parameters by saying (in most cases) that the copy of each generic formal parameter declares a view of the actual. Suppose a name in a generic unit denotes a generic_formal_parameter_declaration. The copy of that name in an instance will denote the copy of that generic_formal_parameter_declaration in the instance. Since the generic_formal_parameter_declaration in the instance declares a view of the actual, the name will denote a view of the actual. 13.d/2 {AI95-00442-01} Other properties of the copy (for example, staticness, categories to which types belong) are recalculated for each instance; this is implied by the fact that it's a copy. 13.e/2 {AI95-00317-01} Although the generic_formal_part is included in an instance, the declarations in the generic_formal_part are only visible outside the instance in the case of a generic formal package whose formal_package_actual_part includes one or more <> indicators - see 12.7. 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. 14.a Ramification: See 8.6, "The Context of Overload Resolution" for definitions of "interpretation" and "overloading rule." 14.b Even the generic_formal_parameter_declarations have corresponding declarations in the instance, which declare views of the actuals. 14.c Although the declarations in the instance are copies of those in the generic unit, they often have quite different properties, as explained below. For example a constant declaration in the generic unit might declare a nonstatic constant, whereas the copy of that declaration might declare a static constant. This can happen when the staticness depends on some generic formal. 14.d This rule is partly a ramification of the "current instance" rule in 8.6, "The Context of Overload Resolution". Note that that rule doesn't cover the generic_formal_part. 14.e Although the overloading rules are not observed in the instance, they are, of course, observed in the _instantiation in order to determine the interpretation of the constituents of the _instantiation. 14.f Since children are considered to occur within their parent's declarative region, the above rule applies to a name that denotes a child of a generic unit, or a declaration inside such a child. 14.g Since the Syntax Rules are overloading rules, it is possible (legal) to violate them in an instance. For example, it is possible for an instance body to occur in a package_specification, even though the Syntax Rules forbid bodies in package_specifications. 15 In an instance, a generic_formal_parameter_declaration declares a view whose properties are identical to those of the actual, except as specified in 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. 15.a Ramification: In an instance, there are no "properties" of types and subtypes that come from the formal. The primitive operations of the type come from the formal, but these are declarations in their own right, and are therefore handled separately. 15.b Note that certain properties that come from the actuals are irrelevant in the instance. For example, if an actual type is of a class deeper in the derived-type hierarchy than the formal, it is impossible to call the additional operations of the deeper class in the instance, because any such call would have to be a copy of some corresponding call in the generic unit, which would have been illegal. However, it is sometimes possible to reach into the specification of the instance from outside, and notice such properties. For example, one could pass an object declared in the instance specification to one of the additional operations of the deeper type. 15.c/2 {AI95-00114-01} A formal_type_declaration can contain discriminant_specifications, a formal_subprogram_declaration can contain parameter_specifications, and a formal_package_declaration can contain many kinds of declarations. These are all inside the generic unit, and have corresponding declarations in the instance. 15.d This rule implies, for example, that if a subtype in a generic unit is a subtype of a generic formal subtype, then the corresponding subtype in the instance is a subtype of the corresponding actual subtype. 15.e For a generic_instantiation, if a generic actual is a static [(scalar or string)] subtype, then each use of the corresponding formal parameter within the specification of the instance is considered to be static. (See AI83-00409.) 15.f Similarly, if a generic actual is a static expression and the corresponding formal parameter has a static [(scalar or string)] subtype, then each use of the formal parameter in the specification of the instance is considered to be static. (See AI83-00505.) 15.g If a primitive subprogram of a type derived from a generic formal derived tagged type is not overriding (that is, it is a new subprogram), it is possible for the copy of that subprogram in an instance to override a subprogram inherited from the actual. For example: 15.h type T1 is tagged record ... end record; 15.i generic type Formal is new T1; package G is type Derived_From_Formal is new Formal with record ... end record; procedure Foo(X : in Derived_From_Formal); -- Does not override anything. end G; 15.j type T2 is new T1 with record ... end record; procedure Foo(X : in T2); 15.k package Inst is new G(Formal => T2); 15.l In the instance Inst, the declaration of Foo for Derived_From_Formal overrides the Foo inherited from T2. 15.m/1 Implementation Note: {8652/0009} {AI95-00137-01} For formal types, an implementation that shares the code among multiple instances of the same generic unit needs to beware that things like parameter passing mechanisms (by-copy vs. by-reference) and aspect_clauses are determined by 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.] 17.a Proof: This rule is stated officially in 8.3, "Visibility". 17.b Ramification: The new ones follow from the class(es) of the formal types. For example, for a type T derived from a generic formal private type, if the actual is Integer, then the copy of T in the instance has a "+" primitive operator, which can be called from outside the instance (assuming T is declared in the visible part of the instance). 17.c AI83-00398. 17.d/2 {AI95-00442-01} Since an actual type is always in the category determined for the formal, the new subprograms hide all of the copied ones, except for a declaration of "/=" that corresponds to an explicit declaration of "=". Such "/=" operators are special, because unlike other implicit declarations of primitive subprograms, they do not appear by virtue of the class, but because of an explicit declaration of "=". If the declaration of "=" is implicit (and therefore overridden in the instance), then a corresponding implicitly declared "/=" is also overridden. But if the declaration of "=" is explicit (and therefore not overridden in the instance), then a corresponding implicitly declared "/=" is not overridden either, even though it's implicit. 17.e Note that the copied ones can be called from inside the instance, even though they are hidden from all visibility, because the names are resolved in the generic unit - visibility is irrelevant for calls in the instance. 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. 18.a Ramification: For example: 18.b type Ancestor is tagged null record; 18.c generic type Formal is new Ancestor with private; package G is type T is new Formal with null record; procedure P(X : in T); -- (1) private procedure Q(X : in T); -- (2) end G; 18.d type Actual is new Ancestor with null record; procedure P(X : in Actual); procedure Q(X : in Actual); 18.e package Instance is new G(Formal => Actual); 18.f In the instance, the copy of P at (1) overrides Actual's P, whereas the copy of Q at (2) does not override anything; in implementation terms, it occupies a separate slot in the type descriptor. 18.g Reason: The reason for this rule is so a programmer writing an _instantiation need not look at the private part of the generic in order to determine which subprograms will be overridden. 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)]. 19.a Discussion: Note that this rule is not a violation of the generic contract model, because it is not a Legality Rule. Some implementations may be able to check this rule at compile time, but that requires access to all the bodies, so we allow implementations to check the rule at link time. 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. 20.a Ramification: Note that if the evaluation of a default depends on some side effect of some other evaluation, the order is still arbitrary. 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). 21.a To be honest: Actually, the actual is evaluated only if evaluation is defined for that kind of construct - we don't actually " evaluate" subtype_marks. NOTES 22 5 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. 22.a Ramification: If two overloaded subprograms declared in a generic package specification differ only by the (formal) type of their parameters and results, then there exist legal instantiations for which all calls of these subprograms from outside the instance are ambiguous. For example: 22.b generic type A is (<>); type B is private; package G is function Next(X : A) return A; function Next(X : B) return B; end G; 22.c package P is new G(A => Boolean, B => Boolean); -- All calls of P.Next are ambiguous. 22.d Ramification: The following example illustrates some of the subtleties of the substitution of formals and actuals: 22.e generic type T1 is private; -- A predefined "=" operator is implicitly declared here: -- function "="(Left, Right : T1) return Boolean; -- Call this "="(1). package G is subtype S1 is T1; -- So we can get our hands on the type from -- outside an instance. type T2 is new T1; -- An inherited "=" operator is implicitly declared here: -- function "="(Left, Right : T2) return Boolean; -- Call this "="(2). 22.f T1_Obj : T1 := ...; Bool_1 : Boolean := T1_Obj = T1_Obj; 22.g T2_Obj : T2 := ...; Bool_2 : Boolean := T2_Obj = T2_Obj; end G; ... 22.h package P is type My_Int is new Integer; -- A predefined "=" operator is implicitly declared here: -- function "="(Left, Right : My_Int) return Boolean; -- Call this "="(3). function "="(X, Y : My_Int) return Boolean; -- Call this "="(4). -- "="(3) is hidden from all visibility by "="(4). -- Nonetheless, "="(3) can "reemerge" in certain circumstances. end P; use P; ... package I is new G(T1 => My_Int); -- "="(5) is declared in I (see below). use I; 22.i Another_T1_Obj : S1 := 13; -- Can't denote T1, but S1 will do. Bool_3 : Boolean := Another_T1_Obj = Another_T1_Obj; 22.j Another_T2_Obj : T2 := 45; Bool_4 : Boolean := Another_T2_Obj = Another_T2_Obj; 22.k Double : T2 := T2_Obj + Another_T2_Obj; 22.l In the instance I, there is a copy of "="(1) (call it "="(1i)) and "="(2) (call it "="(2i)). The "="(1i) and "="(2i) declare views of the predefined "=" of My_Int (that is, "="(3)). In the initialization of Bool_1 and Bool_2 in the generic unit G, the names "=" denote "="(1) and "="(2), respectively. Therefore, the copies of these names in the instances denote "="(1i) and "="(2i), respectively. Thus, the initialization of I.Bool_1 and I.Bool_2 call the predefined equality operator of My_Int; they will not call "="(4). 22.m The declarations "="(1i) and "="(2i) are hidden from all visibility. This prevents them from being called from outside the instance. 22.n The declaration of Bool_3 calls "="(4). 22.o The instance I also contains implicit declarations of the primitive operators of T2, such as "=" (call it "="(5)) and "+". These operations cannot be called from within the instance, but the declaration of Bool_4 calls "="(5). Examples 23 Examples of generic instantiations (see 12.1): 24 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 Square is new Squaring(Item => Matrix, "*" => Matrix_Product); function Square 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, " Generic Bodies" for the body of Sigma) 29 use Int_Vectors; M : Integer := Sigma(T); -- 150 Inconsistencies With Ada 83 29.a In Ada 83, all explicit actuals are evaluated before all defaults, and the defaults are evaluated in the order of the formal declarations. This ordering requirement is relaxed in Ada 95. Incompatibilities With Ada 83 29.b We have attempted to remove every violation of the contract model. Any remaining contract model violations should be considered bugs in the RM95. The unfortunate property of reverting to the predefined operators of the actual types is retained for upward compatibility. (Note that fixing this would require subtype conformance rules.) However, tagged types do not revert in this sense. Extensions to Ada 83 29.c The syntax rule for explicit_generic_actual_parameter is modified to allow a package_instance_name. Wording Changes from Ada 83 29.d The fact that named associations cannot be used for two formal subprograms with the same defining name is moved to AARM-only material, because it is a ramification of other rules, and because it is not of interest to the average user. 29.e/2 {AI95-00114-01} The rule that "An explicit explicit_generic_actual_parameter shall not be supplied more than once for a given generic formal parameter" seems to be missing from RM83, although it was clearly the intent. 29.f In the explanation that the instance is a copy of the template, we have left out RM83-12.3(5)'s "apart from the generic formal part", because it seems that things in the formal part still need to exist in instances. This is particularly true for generic formal packages, where you're sometimes allowed to reach in and denote the formals of the formal package from outside it. This simplifies the explanation of what each name in an instance denotes: there are just two cases: the declaration can be inside or outside (where inside needs to include the generic unit itself). Note that the RM83 approach of listing many cases (see RM83-12.5(5-14)) would have become even more unwieldy with the addition of generic formal packages, and the declarations that occur therein. 29.g We have corrected the definition of the elaboration of a generic_instantiation (RM83-12.3(17)); we don't elaborate entities, and the instance is not "implicit." 29.h In RM83, there is a rule saying the formal and actual shall match, and then there is much text defining what it means to match. Here, we simply state all the latter text as rules. For example, "A formal foo is matched by an actual greenish bar" becomes "For a formal foo, the actual shall be a greenish bar." This is necessary to split the Name Resolution Rules from the Legality Rules. Besides, there's really no need to define the concept of matching for generic parameters. Extensions to Ada 95 29.i/2 {AI95-00218-03} An overriding_indicator (see 8.3.1) is allowed on a subprogram instantiation. Extensions to Ada 2005 29.j/3 {AI05-0183-1} An optional aspect_specification can be used in a generic_instantiation. This is described in 13.1.1. Wording Changes from Ada 2005 29.k/3 {AI05-0118-1} Correction: Added a definition for positional parameters, as this is missing from Ada 95 and Ada 2005. 12.4 Formal Objects 1 [ A generic formal object can be used to pass a value or variable to a generic unit.] Language Design Principles 1.a A generic formal object of mode in is like a constant initialized to the value of the explicit_generic_actual_parameter. 1.b A generic formal object of mode in out is like a renaming of the explicit_generic_actual_parameter. Syntax 2/3 {AI95-00423-01} {AI05-0005-1} {AI05-0183-1} formal_object_declaration ::= defining_identifier_list : mode [null_exclusion] subtype_mark [:= default_expression] [aspect_specification]; | defining_identifier_list : mode access_definition [:= default_expression] [aspect_specification]; Name Resolution Rules 3 The expected type for the default_expression, if any, of a formal object is the type of the formal object. 4 For a generic formal object of mode in, the expected type for the actual is the type of the formal. 5/2 {AI95-00423-01} For a generic formal object of mode in out, the type of the actual shall resolve to the type determined by the subtype_mark, or for a formal_object_declaration with an access_definition, to a specific anonymous access type. If the anonymous access type is an access-to-object type, the type of the actual shall have the same designated type as that of the access_definition. If the anonymous access type is an access-to-subprogram type, the type of the actual shall have a designated profile which is type conformant with that of the access_definition. 5.a Reason: See the corresponding rule for object_renaming_declarations for a discussion of the reason for this rule. Legality Rules 6 If a generic formal object has a default_expression, then the mode shall be in [(either explicitly or by default)]; otherwise, its mode shall be either in or in out. 6.a Ramification: Mode out is not allowed for generic formal objects. 7 For a generic formal object of mode in, the actual shall be an expression. For a generic formal object of mode in out, the actual shall be a name that denotes a variable for which renaming is allowed (see 8.5.1). 7.a To be honest: The part of this that requires an expression or name is a Name Resolution Rule, but that's too pedantic to worry about. (The part about denoting a variable, and renaming being allowed, is most certainly not a Name Resolution Rule.) 8/2 {AI95-00287-01} {AI95-00423-01} In the case where the type of the formal is defined by an access_definition, the type of the actual and the type of the formal: 8.1/2 * {AI95-00423-01} shall both be access-to-object types with statically matching designated subtypes and with both or neither being access-to-constant types; or 8.2/2 * {AI95-00423-01} shall both be access-to-subprogram types with subtype conformant designated profiles. 8.3/2 {AI95-00423-01} For a formal_object_declaration with a null_exclusion or an access_definition that has a null_exclusion: 8.4/2 * if the actual matching the formal_object_declaration denotes the generic formal object of another generic unit G, and the instantiation containing the actual occurs within the body of G or within the body of a generic unit declared within the declarative region of G, then the declaration of the formal object of G shall have a null_exclusion; 8.5/2 * otherwise, the subtype of the actual matching the formal_object_declaration shall exclude null. In addition to the places where Legality Rules normally apply (see 12.3), this rule applies also in the private part of an instance of a generic unit. 8.a/2 Reason: {AI95-00287-01} {AI95-00423-01} This rule prevents " lying". Null must never be the value of an object with an explicit null_exclusion. The first bullet is an assume-the-worst rule which prevents trouble in generic bodies (including bodies of child units) when the subtype of the formal object excludes null implicitly. Static Semantics 9/2 {AI95-00255-01} {AI95-00423-01} A formal_object_declaration declares a generic formal object. The default mode is in. For a formal object of mode in, the nominal subtype is the one denoted by the subtype_mark or access_definition in the declaration of the formal. For a formal object of mode in out, its type is determined by the subtype_mark or access_definition in the declaration; its nominal subtype is nonstatic, even if the subtype_mark denotes a static subtype; for a composite type, its nominal subtype is unconstrained if the first subtype of the type is unconstrained[, even if the subtype_mark denotes a constrained subtype]. 9.a/2 Reason: {AI95-00255-01} We require that the subtype is unconstrained because a formal in out acts like a renaming, and thus the given subtype is ignored for purposes of matching; any value of the type can be passed. Thus we can assume only that the object is constrained if the first subtype is constrained (and thus there can be no unconstrained subtypes for the type). If we didn't do this, it would be possible to rename or take 'Access of components that could disappear due to an assignment to the whole object. 9.b/2 Discussion: {AI95-00423-01} The two "even if" clauses are OK even though they don't mention access_definitions; an access subtype can neither be a static subtype nor be a composite type. 10/2 {AI95-00269-01} In an instance, a formal_object_declaration of mode in is a full constant declaration and declares a new stand-alone constant object whose initialization expression is the actual, whereas a formal_object_declaration of mode in out declares a view whose properties are identical to those of the actual. 10.a/2 Ramification: {AI95-00287-01} These rules imply that generic formal objects of mode in are passed by copy (or are built-in-place for a limited type), whereas generic formal objects of mode in out are passed by reference. 10.b Initialization and finalization happen for the constant declared by a formal_object_declaration of mode in as for any constant; see 3.3.1, "Object Declarations" and 7.6, " Assignment and Finalization". 10.c In an instance, the subtype of a generic formal object of mode in is as for the equivalent constant. In an instance, the subtype of a generic formal object of mode in out is the subtype of the corresponding generic actual. Dynamic Semantics 11 For the evaluation of a generic_association for a formal object of mode in, a constant object is created, the value of the actual parameter is converted to the nominal subtype of the formal object, and assigned to the object[, including any value adjustment - see 7.6]. 11.a Ramification: This includes evaluating the actual and doing a subtype conversion, which might raise an exception. 11.b Discussion: The rule for evaluating a generic_association for a formal object of mode in out is covered by the general Dynamic Semantics rule in 12.3. NOTES 12 6 The constraints that apply to a generic formal object of mode in out are those of the corresponding generic actual parameter (not those implied by the subtype_mark that appears in the formal_object_declaration). Therefore, to avoid confusion, it is recommended that the name of a first subtype be used for the declaration of such a formal object. 12.a Ramification: Constraint checks are done at instantiation time for formal objects of mode in, but not for formal objects of mode in out. Extensions to Ada 83 12.b In Ada 83, it is forbidden to pass a (nongeneric) formal parameter of mode out, or a subcomponent thereof, to a generic formal object of mode in out. This restriction is removed in Ada 95. Wording Changes from Ada 83 12.c We make "mode" explicit in the syntax. RM83 refers to the mode without saying what it is. This is also more uniform with the way (nongeneric) formal parameters are defined. 12.d We considered allowing mode out in Ada 95, for uniformity with (nongeneric) formal parameters. The semantics would be identical for modes in out and out. (Note that generic formal objects of mode in out are passed by reference. Note that for (nongeneric) formal parameters that are allowed to be passed by reference, the semantics of in out and out is the same. The difference might serve as documentation. The same would be true for generic formal objects, if out were allowed, so it would be consistent.) We decided not to make this change, because it does not produce any important benefit, and any change has some cost. Extensions to Ada 95 12.e/2 {AI95-00287-01} A generic formal in object can have a limited type. The actual for such an object must be built-in-place via a function_call or aggregate, see 7.5. 12.f/2 {AI95-00423-01} A generic formal object can have a null_exclusion or an anonymous access type. Wording Changes from Ada 95 12.g/2 {AI95-00255-01} Clarified that the nominal subtype of a composite formal in out object is unconstrained if the first subtype of the type is unconstrained. 12.h/2 {AI95-00269-01} Clarified that a formal in object can be static when referenced from outside of the instance (by declaring such an object to be a full constant declaration). Extensions to Ada 2005 12.i/3 {AI05-0183-1} An optional aspect_specification can be used in a formal_object_declaration. This is described in 13.1.1. 12.5 Formal Types 1/2 {AI95-00442-01} [A generic formal subtype can be used to pass to a generic unit a subtype whose type is in a certain category of types.] 1.a Reason: We considered having intermediate syntactic categories formal_integer_type_definition, formal_real_type_definition, and formal_fixed_point_definition, to be more uniform with the syntax rules for non-generic-formal types. However, that would make the rules for formal types slightly more complicated, and it would cause confusion, since formal_discrete_type_definition would not fit into the scheme very well. Syntax 2/3 {AI05-0213-1} formal_type_declaration ::= formal_complete_type_declaration | formal_incomplete_type_declaration 2.1/3 {AI05-0183-1} {AI05-0213-1} formal_complete_type_declaration ::= type defining_identifier[discriminant_part ] is formal_type_definition [aspect_specification]; 2.2/3 {AI05-0213-1} formal_incomplete_type_declaration ::= type defining_identifier[discriminant_part] [is tagged]; 3/2 {AI95-00251-01} formal_type_definition ::= formal_private_type_definition | formal_derived_type_definition | formal_discrete_type_definition | formal_signed_integer_type_definition | formal_modular_type_definition | formal_floating_point_definition | formal_ordinary_fixed_point_definition | formal_decimal_fixed_point_definition | formal_array_type_definition | formal_access_type_definition | formal_interface_type_definition Legality Rules 4 For a generic formal subtype, the actual shall be a subtype_mark; it denotes the (generic) actual subtype. 4.a Ramification: When we say simply "formal" or "actual" (for a generic formal that denotes a subtype) we're talking about the subtype, not the type, since a name that denotes a formal_type_declaration denotes a subtype, and the corresponding actual also denotes a subtype. Static Semantics 5 A formal_type_declaration declares a (generic) formal type, and its first subtype, the (generic) formal subtype. 5.a Ramification: A subtype (other than the first subtype) of a generic formal type is not a generic formal subtype. 6/3 {AI95-00442-01} {AI05-0213-1} The form of a formal_type_definition determines a category (of types) to which the formal type belongs. For a formal_private_type_definition the reserved words tagged and limited indicate the category of types (see 12.5.1). The reserved word tagged also plays this role in the case of a formal_incomplete_type_declaration. For a formal_derived_type_definition the category of types is the derivation class rooted at the ancestor type. For other formal types, the name of the syntactic category indicates the category of types; a formal_discrete_type_definition defines a discrete type, and so on. 6.a Reason: This rule is clearer with the flat syntax rule for formal_type_definition given above. Adding formal_integer_type_definition and others would make this rule harder to state clearly. 6.b/2 {AI95-00442-01} We use "category' rather than "class" above, because the requirement that classes are closed under derivation is not important here. Moreover, there are interesting categories that are not closed under derivation. For instance, limited and interface are categories that do not form classes. Legality Rules 7/2 {AI95-00442-01} The actual type shall be in the category determined for the formal. 7.a/2 Ramification: {AI95-00442-01} For example, if the category determined for the formal is the category of all discrete types, then the actual has to be discrete. 7.b/2 {AI95-00442-01} Note that this rule does not require the actual to belong to every category to which the formal belongs. For example, formal private types are in the category of composite types, but the actual need not be composite. Furthermore, one can imagine an infinite number of categories that are just arbitrary sets of types (even though we don't give them names, since they are uninteresting). We don't want this rule to apply to those categories. 7.c/2 {AI95-00114-01} {AI95-00442-01} "Limited" is not an " interesting" category, but "nonlimited" is; it is legal to pass a nonlimited type to a limited formal type, but not the other way around. The reserved word limited really represents a category containing both limited and nonlimited types. "Private" is not a category for this purpose; a generic formal private type accepts both private and nonprivate actual types. 7.d/2 {AI95-00442-01} It is legal to pass a class-wide subtype as the actual if it is in the right category, so long as the formal has unknown discriminants. Static Semantics 8/3 {8652/0037} {AI95-00043-01} {AI95-00233-01} {AI95-00442-01} {AI05-0029-1} [The formal type also belongs to each category that contains the determined category.] The primitive subprograms of the type are as for any type in the determined category. For a formal type other than a formal derived type, these are the predefined operators of the type. For an elementary formal type, the predefined operators are implicitly declared immediately after the declaration of the formal type. For a composite formal type, the predefined operators are implicitly declared either immediately after the declaration of the formal type, or later immediately within the declarative region in which the type is declared according to the rules of 7.3.1. In an instance, the copy of such an implicit declaration declares a view of the predefined operator of the actual type, even if this operator has been overridden for the actual type and even if it is never declared for the actual type. [The rules specific to formal derived types are given in 12.5.1.] 8.a/2 Ramification: {AI95-00442-01} All properties of the type are as for any type in the category. Some examples: The primitive operations available are as defined by the language for each category. The form of constraint applicable to a formal type in a subtype_indication depends on the category of the type as for a nonformal type. The formal type is tagged if and only if it is declared as a tagged private type, or as a type derived from a (visibly) tagged type. (Note that the actual type might be tagged even if the formal type is not.) 8.b/3 Reason: {AI05-0029-1} The somewhat cryptic phrase "even if it is never declared" is intended to deal with the following oddity: 8.c/3 package Q is type T is limited private; private type T is range 1 .. 10; end Q; 8.d/3 generic type A is array (Positive range <>) of T; package Q.G is A1, A2 : A (1 .. 1); private B : Boolean := A1 = A2; end Q.G; 8.e/3 with Q.G; package R is type C is array (Positive range <>) of Q.T; 8.f/3 package I is new Q.G (C); -- Where is the predefined "=" for C? end R; 8.g/3 An "=" is available for the formal type A in the private part of Q.G. However, no "=" operator is ever declared for type C, because its component type Q.T is limited. Still, in the instance I the name "=" declares a view of the "=" for C which exists-but-is-never-declared. NOTES 9 7 Generic formal types, like all types, are not named. Instead, a name can denote a generic formal subtype. Within a generic unit, a generic formal type is considered as being distinct from all other (formal or nonformal) types. 9.a Proof: This follows from the fact that each formal_type_declaration declares a type. 10 8 A discriminant_part is allowed only for certain kinds of types, and therefore only for certain kinds of generic formal types. See 3.7. 10.a Ramification: The term "formal floating point type" refers to a type defined by a formal_floating_point_definition. It does not include a formal derived type whose ancestor is floating point. Similar terminology applies to the other kinds of formal_type_definition. Examples 11 Examples of generic formal types: 12 type Item is private; type Buffer(Length : Natural) is limited private; 13 type Enum is (<>); type Int is range <>; type Angle is delta <>; type Mass is digits <>; 14 type Table is array (Enum) of Item; 15 Example of a generic formal part declaring a formal integer type: 16 generic type Rank is range <>; First : Rank := Rank'First; Second : Rank := First + 1; -- the operator "+" of the type Rank Wording Changes from Ada 83 16.a RM83 has separate sections "Generic Formal Xs" and "Matching Rules for Formal Xs" (for various X's) with most of the text redundant between the two. We have combined the two in order to reduce the redundancy. In RM83, there is no "Matching Rules for Formal Types" section; nor is there a "Generic Formal Y Types" section (for Y = Private, Scalar, Array, and Access). This causes, for example, the duplication across all the "Matching Rules for Y Types" sections of the rule that the actual passed to a formal type shall be a subtype; the new organization avoids that problem. 16.b The matching rules are stated more concisely. 16.c We no longer consider the multiplying operators that deliver a result of type universal_fixed to be predefined for the various types; there is only one of each in package Standard. Therefore, we need not mention them here as RM83 had to. Wording Changes from Ada 95 16.d/2 {8652/0037} {AI95-00043-01} {AI95-00233-01} Corrigendum 1 corrected the wording to properly define the location where operators are defined for formal array types. The wording here was inconsistent with that in 7.3.1, "Private Operations". For the Amendment, this wording was corrected again, because it didn't reflect the Corrigendum 1 revisions in 7.3.1. 16.e/2 {AI95-00251-01} Formal interface types are defined; see 12.5.5 , "Formal Interface Types". 16.f/2 {AI95-00442-01} We use "determines a category" rather than class, since not all interesting properties form a class. Extensions to Ada 2005 16.g/3 {AI05-0183-1} An optional aspect_specification can be used in a formal_type_declaration. This is described in 13.1.1. Wording Changes from Ada 2005 16.h/3 {AI05-0029-1} Correction: Updated the wording to acknowledge the possibility of operations that are never declared for an actual type but still can be used inside of a generic unit. 16.i/3 {AI05-0213-1} {AI05-0299-1} Formal incomplete types are added; these are documented as an extension in the next subclause. 12.5.1 Formal Private and Derived Types 1/3 {AI95-00442-01} {AI05-0213-1} [In its most general form, the category determined for a formal private type is all types, but the category can be restricted to only nonlimited types or to only tagged types. Similarly, the category for a formal incomplete type is all types but the category can be restricted to only tagged types; unlike other formal types, the actual type does not need to be able to be frozen (see 13.14). The category determined for a formal derived type is the derivation class rooted at the ancestor type.] 1.a/3 Proof: {AI95-00442-01} {AI05-0213-1} The first two rules are given normatively below, and the third rule is given normatively in 12.5; they are repeated here to give a capsule summary of what this subclause is about. 1.b/3 Ramification: {AI05-0213-1} Since the actual of a formal incomplete type does not need to be able to be frozen, the actual can be an incomplete type or a partial view before its completion. Syntax 2 formal_private_type_definition ::= [[abstract] tagged] [limited] private 3/2 {AI95-00251-01} {AI95-00419-01} {AI95-00443-01} formal_derived_type_definition ::= [abstract] [limited | synchronized] new subtype_mark [[and interface_list]with private] Legality Rules 4 If a generic formal type declaration has a known_discriminant_part, then it shall not include a default_expression for a discriminant. 4.a Ramification: Consequently, a generic formal subtype with a known_discriminant_part is an indefinite subtype, so the declaration of a stand-alone variable has to provide a constraint on such a subtype, either explicitly, or by its initial value. 5/3 {AI95-00401-01} {AI95-00419-01} {AI95-00443-01} {AI05-0237-1} The ancestor subtype of a formal derived type is the subtype denoted by the subtype_mark of the formal_derived_type_definition. For a formal derived type declaration, the reserved words with private shall appear if and only if the ancestor type is a tagged type; in this case the formal derived type is a private extension of the ancestor type and the ancestor shall not be a class-wide type. [Similarly, an interface_list or the optional reserved words abstract or synchronized shall appear only if the ancestor type is a tagged type]. The reserved word limited or synchronized shall appear only if the ancestor type [and any progenitor types] are limited types. The reserved word synchronized shall appear (rather than limited) if the ancestor type or any of the progenitor types are synchronized interfaces. The ancestor type shall be a limited interface if the reserved word synchronized appears. 5.a Reason: We use the term "ancestor" here instead of "parent" because the actual can be any descendant of the ancestor, not necessarily a direct descendant. 5.b/3 {AI95-00419-01} {AI05-0005-1} We require the ancestor type to be limited when limited appears so that we avoid oddities like limited integer types. Normally, limited means "match anything" for a generic formal, but it was felt that allowing limited elementary types to be declared was just too weird. Integer still matches a formal limited private type; it is only a problem when the type is known to be elementary. Note that the progenitors are required to be limited by rules in 3.9.4, thus that part of the rule is redundant. 5.c/2 {AI95-00443-01} We require that synchronized appear if the ancestor or any of the progenitors are synchronized, so that property is explicitly given in the program text - it is not automatically inherited from the ancestors. However, it can be given even if neither the ancestor nor the progenitors are synchronized. 5.1/4 {AI95-00251-01} {AI95-00401-01} {AI95-00443-01} {AI05-0087-1} {AI12-0036-1} The actual type for a formal derived type shall be a descendant of [the ancestor type and] every progenitor of the formal type. If the formal type is nonlimited, the actual type shall be nonlimited. The actual type for a formal derived type shall be tagged if and only if the formal derived type is a private extension. If the reserved word synchronized appears in the declaration of the formal derived type, the actual type shall be a synchronized tagged type. 5.d/2 Proof: The actual type has to be a descendant of the ancestor type, in order that it be in the correct class. Thus, that part of the rule is redundant. 5.e/3 Discussion: {AI05-0005-1} For a nonformal private extension, we require the partial view to be synchronized if the full view is synchronized tagged. This does not apply to a formal private extension - it is OK if the formal is not synchronized. Any attempt to extend the formal type will be rechecked in the instance, where the rule disallowing extending a synchronized noninterface type will be enforced. This is consistent with the "no hidden interfaces" rule also applying only to nonformal private extensions, as well as the rule that a limited nonformal private extension implies a limited full type. Formal private extensions are exempted from all these rules to enable the construction of generics that can be used with the widest possible range of types. In particular, an indefinite tagged limited formal private type can match any "concrete" actual tagged type. 5.f/3 {AI05-0087-1} A type (including formal types) derived from a limited interface could be nonlimited; we do not want a limited type derived from such an interface to match a nonlimited formal derived type. Otherwise, we could assign limited objects. Thus, we have to explicitly ban this case. 5.g/4 {AI12-0036-1} If we allowed actual types that differ from the kind of the formal derived type, we could allow type conversions that would not be allowed outside of the generic. That would be particularly problematical if the actual is a tagged type with extension components; we could have created an object of the type that is missing those components by converting from the ancestor type to a formal derived type that is not an extension. 6/3 {AI05-0213-1} If a formal private or derived subtype is definite, then the actual subtype shall also be definite. 6.a Ramification: On the other hand, for an indefinite formal subtype, the actual can be either definite or indefinite. 6.1/3 {AI05-0213-1} A formal_incomplete_type_declaration declares a formal incomplete type. The only view of a formal incomplete type is an incomplete view. [Thus, a formal incomplete type is subject to the same usage restrictions as any other incomplete type - see 3.10.1.] 7 For a generic formal derived type with no discriminant_part: 8 * If the ancestor subtype is constrained, the actual subtype shall be constrained, and shall be statically compatible with the ancestor; 8.a Ramification: In other words, any constraint on the ancestor subtype is considered part of the "contract." 9 * If the ancestor subtype is an unconstrained access or composite subtype, the actual subtype shall be unconstrained. 9.a Reason: This rule ensures that if a composite constraint is allowed on the formal, one is also allowed on the actual. If the ancestor subtype is an unconstrained scalar subtype, the actual is allowed to be constrained, since a scalar constraint does not cause further constraints to be illegal. 10 * If the ancestor subtype is an unconstrained discriminated subtype, then the actual shall have the same number of discriminants, and each discriminant of the actual shall correspond to a discriminant of the ancestor, in the sense of 3.7. 10.a Reason: This ensures that if a discriminant constraint is given on the formal subtype, the corresponding constraint in the instance will make sense, without additional run-time checks. This is not necessary for arrays, since the bounds cannot be overridden in a type extension. An unknown_discriminant_part may be used to relax these matching requirements. 10.1/2 * {AI95-00231-01} If the ancestor subtype is an access subtype, the actual subtype shall exclude null if and only if the ancestor subtype excludes null. 10.b/2 Reason: We require that the "excludes null" property match, because it would be difficult to write a correct generic for a formal access type without knowing this property. Many typical algorithms and techniques will not work for a subtype that excludes null (setting an unused component to null, default-initialized objects, and so on). We want this sort of requirement to be reflected in the contract of the generic. 11/3 {AI05-0213-1} The declaration of a formal derived type shall not have a known_discriminant_part. For a generic formal private or incomplete type with a known_discriminant_part: 12 * The actual type shall be a type with the same number of discriminants. 13 * The actual subtype shall be unconstrained. 14 * The subtype of each discriminant of the actual type shall statically match the subtype of the corresponding discriminant of the formal type. 14.a Reason: We considered defining the first and third rule to be called "subtype conformance" for discriminant_parts. We rejected that idea, because it would require implicit (inherited) discriminant_parts, which seemed like too much mechanism. 15 [For a generic formal type with an unknown_discriminant_part, the actual may, but need not, have discriminants, and may be definite or indefinite.] 15.1/4 {AI12-0095-1} When enforcing Legality Rules, for the purposes of determining within a generic body whether a type is unconstrained in any partial view, a discriminated subtype is considered to have a constrained partial view if it is a descendant of an untagged generic formal private or derived type. Static Semantics 16/2 {AI95-00442-01} The category determined for a formal private type is as follows: 17/2 Type Definition Determined Category limited private the category of all types private the category of all nonlimited types tagged limited private the category of all tagged types tagged private the category of all nonlimited tagged types 18 [The presence of the reserved word abstract determines whether the actual type may be abstract.] 18.1/3 {AI05-0213-1} The category determined for a formal incomplete type is the category of all types, unless the formal_type_declaration includes the reserved word tagged; in this case, it is the category of all tagged types. 19 A formal private or derived type is a private or derived type, respectively. A formal derived tagged type is a private extension. [A formal private or derived type is abstract if the reserved word abstract appears in its declaration.] 20/3 {AI95-00233-01} {AI05-0110-1} For a formal derived type, the characteristics (including components, but excluding discriminants if there is a new discriminant_part), predefined operators, and inherited user-defined primitive subprograms are determined by its ancestor type and its progenitor types (if any), in the same way that those of a derived type are determined by those of its parent type and its progenitor types (see 3.4 and 7.3.1). 21/3 {8652/0038} {AI95-00202} {AI95-00233-01} {AI95-00401-01} {AI05-0029-1} {AI05-0110-1} In an instance, the copy of an implicit declaration of a primitive subprogram of a formal derived type declares a view of the corresponding primitive subprogram of the ancestor or progenitor of the formal derived type, even if this primitive has been overridden for the actual type and even if it is never declared for the actual type. When the ancestor or progenitor of the formal derived type is itself a formal type, the copy of the implicit declaration declares a view of the corresponding copied operation of the ancestor or progenitor. [In the case of a formal private extension, however, the tag of the formal type is that of the actual type, so if the tag in a call is statically determined to be that of the formal type, the body executed will be that corresponding to the actual type.] 21.a/3 Ramification: {AI95-00401-01} {AI05-0239-1} The above rule defining the properties of primitive subprograms in an instance applies even if the subprogram has been overridden or hidden for the actual type. This rule is necessary for untagged types, because their primitive subprograms might have been overridden by operations that are not subtype conformant with the operations defined for the class. For tagged types, the rule still applies, but the primitive subprograms will dispatch to the appropriate implementation based on the type and tag of the operands. Even for tagged types, the formal parameter names and default_expressions are determined by those of the primitive subprograms of the specified ancestor type (or progenitor type, for subprograms inherited from an interface type). 21.b/4 To be honest: {AI12-0030-1} The availability of stream attributes is not formally a characteristic of a type, but it is still determined by the ancestor type for a formal derived type in the same way as the characteristics are. Availability is rechecked in the instance specification. 22/1 For a prefix S that denotes a formal indefinite subtype, the following attribute is defined: 23/3 S'Definite {AI05-0264-1} S'Definite yields True if the actual subtype corresponding to S is definite; otherwise, it yields False. The value of this attribute is of the predefined type Boolean. 23.a/2 Discussion: {AI95-00114-01} Whether an actual subtype is definite or indefinite may have a major effect on the algorithm used in a generic. For example, in a generic I/O package, whether to use fixed-length or variable-length records could depend on whether the actual is definite or indefinite. This attribute is essentially a replacement for the Constrained attribute, which is now considered obsolete. Dynamic Semantics 23.1/3 {AI95-00158-01} {AI05-0071-1} In the case where a formal type has unknown discriminants, and the actual type is a class-wide type T'Class: 23.2/2 * {AI95-00158-01} For the purposes of defining the primitive operations of the formal type, each of the primitive operations of the actual type is considered to be a subprogram (with an intrinsic calling convention - see 6.3.1) whose body consists of a dispatching call upon the corresponding operation of T, with its formal parameters as the actual parameters. If it is a function, the result of the dispatching call is returned. 23.3/2 * {AI95-00158-01} If the corresponding operation of T has no controlling formal parameters, then the controlling tag value is determined by the context of the call, according to the rules for tag-indeterminate calls (see 3.9.2 and 5.2). In the case where the tag would be statically determined to be that of the formal type, the call raises Program_Error. If such a function is renamed, any call on the renaming raises Program_Error. 23.b/2 Discussion: As it states in 6.3.1, the convention of an inherited subprogram of a generic formal tagged type with unknown discriminants is intrinsic. 23.c/2 In the case of a corresponding primitive of T with no controlling formal parameters, the context of the call provides the controlling tag value for the dispatch. If no tag is provided by context, Program_Error is raised rather than resorting to a nondispatching call. For example: 23.d/2 generic type NT(<>) is new T with private; -- Assume T has operation "function Empty return T;" package G is procedure Test(X : in out NT); end G; 23.e/2 package body G is procedure Test(X : in out NT) is begin X := Empty; -- Dispatching based on X'Tag takes -- place if actual is class-wide. declare Y : NT := Empty; -- If actual is class-wide, this raises Program_Error -- as there is no tag provided by context. begin X := Y; -- We never get this far. end; end Test; end G; 23.f/2 type T1 is new T with null record; package I is new G(T1'Class); NOTES 24/2 9 {AI95-00442-01} In accordance with the general rule that the actual type shall belong to the category determined for the formal (see 12.5, "Formal Types"): 25 * If the formal type is nonlimited, then so shall be the actual; 26 * For a formal derived type, the actual shall be in the class rooted at the ancestor subtype. 27 10 The actual type can be abstract only if the formal type is abstract (see 3.9.3). 27.a Reason: This is necessary to avoid contract model problems, since one or more of its primitive subprograms are abstract; it is forbidden to create objects of the type, or to declare functions returning the type. 27.b Ramification: On the other hand, it is OK to pass a nonabstract actual to an abstract formal - abstract on the formal indicates that the actual might be abstract. 28 11 If the formal has a discriminant_part, the actual can be either definite or indefinite. Otherwise, the actual has to be definite. Incompatibilities With Ada 83 28.a Ada 83 does not have unknown_discriminant_parts, so it allows indefinite subtypes to be passed to definite formals, and applies a legality rule to the instance body. This is a contract model violation. Ada 95 disallows such cases at the point of the instantiation. The workaround is to add (<>) as the discriminant_part of any formal subtype if it is intended to be used with indefinite actuals. If that's the intent, then there can't be anything in the generic body that would require a definite subtype. 28.b The check for discriminant subtype matching is changed from a run-time check to a compile-time check. Extensions to Ada 95 28.c/2 {AI95-00251-01} {AI95-00401-01} {AI95-00419-01} {AI95-00443-01} A generic formal derived type can include progenitors (interfaces) as well as a primary ancestor. It also may include limited to indicate that it is a limited type, and synchronized to indicate that it is a synchronized type. Wording Changes from Ada 95 28.d/2 {8652/0038} {AI95-00202-01} Corrigendum: Corrected wording to define the operations that are inherited when the ancestor of a formal type is itself a formal type to avoid anomalies. 28.e/2 {AI95-00158-01} Added a semantic description of the meaning of operations of an actual class-wide type, as such a type does not have primitive operations of its own. 28.f/2 {AI95-00231-01} Added a matching rule for access subtypes that exclude null. 28.g/2 {AI95-00233-01} The wording for the declaration of implicit operations is corrected to be consistent with 7.3.1 as modified by Corrigendum 1. 28.h/2 {AI95-00442-01} We change to "determines a category" as that is the new terminology (it avoids confusion, since not all interesting properties form a class). Incompatibilities With Ada 2005 28.i/3 {AI05-0087-1} Correction: Added wording to prevent a limited type from being passed to a nonlimited formal derived type. While this was allowed, it would break the contract for the limited type, so hopefully no programs actually depend on that. Extensions to Ada 2005 28.j/3 {AI05-0213-1} Formal incomplete types are a new kind of generic formal; these can be instantiated with incomplete types and unfrozen private types. Wording Changes from Ada 2005 28.k/3 {AI05-0029-1} Correction: Updated the wording to acknowledge the possibility of operations that are never declared for an actual type but still can be used inside of a generic unit. 28.l/3 {AI05-0071-1} Correction: Fixed hole that failed to define what happened for "=" for an untagged private type whose actual is class-wide. 28.m/3 {AI05-0110-1} Correction: Revised the wording for inheritance of characteristics and operations of formal derived types to be reuse the rules as defined for derived types; this should eliminate holes in the wording which have plagued us since Ada 95 was defined (it has been "corrected" four previous times). 28.n/3 {AI05-0237-1} Correction: Added missing rule for the ancestors of formal derived types. The added rule would formally be incompatible, but since it would be impossible to instantiate any such generic, this cannot happen outside of test suites and thus is not documented as an incompatibility. Incompatibilities With Ada 2012 28.o/4 {AI12-0036-1} Corrigendum: Added a requirement that a tagged type only match a formal derived type that is a private extension. This is necessary to prevent type conversions that would not be allowed outside of the generic. We expect that this will be rare, as it only can happen if the formal derived type does not accurately describe the actual type; in most such cases, extension will be desired and a private extension used so that is allowed. Wording Changes from Ada 2012 28.p/4 {AI12-0095-1} Corrigendum: The assume the worst rule for determining within a generic body whether a type is unconstrained in any partial view was moved here. While AI05-0041-1 added it to 3.10.2, it's also needed (at least) in 4.6 and 6.4.1. Thus, it was moved here so that it applies generally. 12.5.2 Formal Scalar Types 1/2 {AI95-00442-01} A formal scalar type is one defined by any of the formal_type_definitions in this subclause. [The category determined for a formal scalar type is the category of all discrete, signed integer, modular, floating point, ordinary fixed point, or decimal types.] 1.a/2 Proof: {AI95-00442-01} The second rule follows from the rule in 12.5 that says that the category is determined by the one given in the name of the syntax production. The effect of the rule is repeated here to give a capsule summary of what this subclause is about. 1.b/2 Ramification: {AI95-00442-01} The "category of a type" includes any classes that the type belongs to. Syntax 2 formal_discrete_type_definition ::= (<>) 3 formal_signed_integer_type_definition ::= range <> 4 formal_modular_type_definition ::= mod <> 5 formal_floating_point_definition ::= digits <> 6 formal_ordinary_fixed_point_definition ::= delta <> 7 formal_decimal_fixed_point_definition ::= delta <> digits <> Legality Rules 8 The actual type for a formal scalar type shall not be a nonstandard numeric type. 8.a Reason: This restriction is necessary because nonstandard numeric types have some number of restrictions on their use, which could cause contract model problems in a generic body. Note that nonstandard numeric types can be passed to formal derived and formal private subtypes, assuming they obey all the other rules, and assuming the implementation allows it (being nonstandard means the implementation might disallow anything). NOTES 9 12 The actual type shall be in the class of types implied by the syntactic category of the formal type definition (see 12.5, " Formal Types"). For example, the actual for a formal_modular_type_definition shall be a modular type. Wording Changes from Ada 95 9.a/2 {AI95-00442-01} We change to "determines a category" as that is the new terminology (it avoids confusion, since not all interesting properties form a class). 12.5.3 Formal Array Types 1/2 {AI95-00442-01} [The category determined for a formal array type is the category of all array types.] 1.a/2 Proof: {AI95-00442-01} This rule follows from the rule in 12.5 that says that the category is determined by the one given in the name of the syntax production. The effect of the rule is repeated here to give a capsule summary of what this subclause is about. Syntax 2 formal_array_type_definition ::= array_type_definition Legality Rules 3 The only form of discrete_subtype_definition that is allowed within the declaration of a generic formal (constrained) array subtype is a subtype_mark. 3.a Reason: The reason is the same as for forbidding constraints in subtype_indications (see 12.1). 4 For a formal array subtype, the actual subtype shall satisfy the following conditions: 5 * The formal array type and the actual array type shall have the same dimensionality; the formal subtype and the actual subtype shall be either both constrained or both unconstrained. 6 * For each index position, the index types shall be the same, and the index subtypes (if unconstrained), or the index ranges (if constrained), shall statically match (see 4.9.1). 7 * The component subtypes of the formal and actual array types shall statically match. 8 * If the formal type has aliased components, then so shall the actual. 8.a Ramification: On the other hand, if the formal's components are not aliased, then the actual's components can be either aliased or not. Examples 9 Example of formal array types: 10 -- given the generic package 11 generic type Item is private; type Index is (<>); type Vector is array (Index range <>) of Item; type Table is array (Index) of Item; package P is ... end P; 12 -- and the types 13 type Mix is array (Color range <>) of Boolean; type Option is array (Color) of Boolean; 14 -- then Mix can match Vector and Option can match Table 15 package R is new P(Item => Boolean, Index => Color, Vector => Mix, Table => Option); 16 -- Note that Mix cannot match Table and Option cannot match Vector Incompatibilities With Ada 83 16.a The check for matching of component subtypes and index subtypes or index ranges is changed from a run-time check to a compile-time check. The Ada 83 rule that "If the component type is not a scalar type, then the component subtypes shall be either both constrained or both unconstrained" is removed, since it is subsumed by static matching. Likewise, the rules requiring that component types be the same is subsumed. Wording Changes from Ada 95 16.b/2 {AI95-00442-01} We change to "determines a category" as that is the new terminology (it avoids confusion, since not all interesting properties form a class). 12.5.4 Formal Access Types 1/2 {AI95-00442-01} [The category determined for a formal access type is the category of all access types.] 1.a/2 Proof: {AI95-00442-01} This rule follows from the rule in 12.5 that says that the category is determined by the one given in the name of the syntax production. The effect of the rule is repeated here to give a capsule summary of what this subclause is about. Syntax 2 formal_access_type_definition ::= access_type_definition Legality Rules 3 For a formal access-to-object type, the designated subtypes of the formal and actual types shall statically match. 4/2 {AI95-00231-01} If and only if the general_access_modifier constant applies to the formal, the actual shall be an access-to-constant type. If the general_access_modifier all applies to the formal, then the actual shall be a general access-to-variable type (see 3.10). If and only if the formal subtype excludes null, the actual subtype shall exclude null. 4.a Ramification: If no _modifier applies to the formal, then the actual type may be either a pool-specific or a general access-to-variable type. 4.a.1/1 Reason: {8652/0109} {AI95-00025-01} Matching an access-to-variable to a formal access-to-constant type cannot be allowed. If it were allowed, it would be possible to create an access-to-variable value designating a constant. 4.b/2 {AI95-00231-01} We require that the "excludes null" property match, because it would be difficult to write a correct generic for a formal access type without knowing this property. Many typical algorithms and techniques will not work for a subtype that excludes null (setting an unused component to null, default-initialized objects, and so on). Even Ada.Unchecked_Deallocation would fail for a subtype that excludes null. Most generics would end up with comments saying that they are not intended to work for subtypes that exclude null. We would rather that this sort of requirement be reflected in the contract of the generic. 5/3 {AI05-0239-1} {AI05-0288-1} For a formal access-to-subprogram subtype, the designated profiles of the formal and the actual shall be subtype conformant. Examples 6 Example of formal access types: 7 -- the formal types of the generic package 8 generic type Node is private; type Link is access Node; package P is ... end P; 9 -- can be matched by the actual types 10 type Car; type Car_Name is access Car; 11 type Car is record Pred, Succ : Car_Name; Number : License_Number; Owner : Person; end record; 12 -- in the following generic instantiation 13 package R is new P(Node => Car, Link => Car_Name); Incompatibilities With Ada 83 13.a The check for matching of designated subtypes is changed from a run-time check to a compile-time check. The Ada 83 rule that "If the designated type is other than a scalar type, then the designated subtypes shall be either both constrained or both unconstrained" is removed, since it is subsumed by static matching. Extensions to Ada 83 13.b Formal access-to-subprogram subtypes and formal general access types are new concepts. Wording Changes from Ada 95 13.c/2 {AI95-00231-01} Added a matching rule for subtypes that exclude null. 13.d/2 {AI95-00442-01} We change to "determines a category" as that is the new terminology (it avoids confusion, since not all interesting properties form a class). Incompatibilities With Ada 2005 13.e/3 {AI05-0288-1} Correction: Matching of formal access-to-subprogram types now uses subtype conformance rather than mode conformance, which is needed to plug a hole. This could cause some instantiations legal in Ada 95 and Ada 2005 to be rejected in Ada 2012. We believe that formal access-to-subprogram types occur rarely, and actuals that are not subtype conformant are rarer still, so this should not happen often. (In addition, one popular compiler has a bug that causes such instances to be rejected, so no code compiled with that compiler could have an incompatibility.) 12.5.5 Formal Interface Types 1/2 {AI95-00251-01} {AI95-00442-01} [The category determined for a formal interface type is the category of all interface types.] 1.a/2 Proof: {AI95-00442-01} This rule follows from the rule in 12.5 that says that the category is determined by the one given in the name of the syntax production. The effect of the rule is repeated here to give a capsule summary of what this subclause is about. 1.b/2 Ramification: Here we're taking advantage of our switch in terminology from "determined class" to "determined category"; by saying "category" rather than "class", we require that any actual type be an interface type, not just some type derived from an interface type. Syntax 2/2 {AI95-00251-01} formal_interface_type_definition ::= interface_type_definition Legality Rules 3/2 {AI95-00251} {AI95-00401} The actual type shall be a descendant of every progenitor of the formal type. 4/2 {AI95-00345} The actual type shall be a limited, task, protected, or synchronized interface if and only if the formal type is also, respectively, a limited, task, protected, or synchronized interface. 4.a/2 Discussion: We require the kind of interface type to match exactly because without that it is almost impossible to properly implement the interface. Examples 5/2 {AI95-00433-01} type Root_Work_Item is tagged private; 6/2 {AI95-00433-01} generic type Managed_Task is task interface; type Work_Item(<>) is new Root_Work_Item with private; package Server_Manager is task type Server is new Managed_Task with entry Start(Data : in out Work_Item); end Server; end Server_Manager; 7/2 {AI95-00433-01} This generic allows an application to establish a standard interface that all tasks need to implement so they can be managed appropriately by an application-specific scheduler. Extensions to Ada 95 7.a/2 {AI95-00251-01} {AI95-00345-01} {AI95-00401-01} {AI95-00442-01} The formal interface type is new. 12.6 Formal Subprograms 1 [ Formal subprograms can be used to pass callable entities to a generic unit.] Language Design Principles 1.a Generic formal subprograms are like renames of the explicit_generic_actual_parameter. Syntax 2/2 {AI95-00260-02} formal_subprogram_declaration ::= formal_concrete_subprogram_declaration | formal_abstract_subprogram_declaration 2.1/3 {AI95-00260-02} {AI05-0183-1} formal_concrete_subprogram_declaration ::= with subprogram_specification [is subprogram_default] [aspect_specification]; 2.2/3 {AI95-00260-02} {AI05-0183-1} formal_abstract_subprogram_declaration ::= with subprogram_specification is abstract [subprogram_default] [aspect_specification]; 3/2 {AI95-00348-01} subprogram_default ::= default_name | <> | null 4 default_name ::= name 4.1/2 {AI95-00260-02} {AI95-00348-01} A subprogram_default of null shall not be specified for a formal function or for a formal_abstract_subprogram_declaration. 4.a/2 Reason: There are no null functions because the return value has to be constructed somehow. We don't allow null for abstract formal procedures, as the operation is dispatching. It doesn't seem appropriate (or useful) to say that the implementation of something is null in the formal type and all possible descendants of that type. This also would define a dispatching operation that doesn't correspond to a slot in the tag of the controlling type, which would be a new concept. Finally, additional rules would be needed to define the meaning of a dispatching null procedure (for instance, the convention of such a subprogram should be intrinsic, but that's not what the language says). It doesn't seem worth the effort. Name Resolution Rules 5 The expected profile for the default_name, if any, is that of the formal subprogram. 5.a/3 Ramification: {AI05-0299-1} This rule, unlike others in this subclause, is observed at compile time of the generic_declaration. 5.b The evaluation of the default_name takes place during the elaboration of each instantiation that uses the default, as defined in 12.3, "Generic Instantiation". 6 For a generic formal subprogram, the expected profile for the actual is that of the formal subprogram. Legality Rules 7/3 {AI05-0239-1} The profiles of the formal and any named default shall be mode conformant. 7.a/3 Ramification: {AI05-0299-1} This rule, unlike others in this subclause, is checked at compile time of the generic_declaration. 8/3 {AI05-0239-1} The profiles of the formal and actual shall be mode conformant. 8.1/2 {AI95-00423-01} For a parameter or result subtype of a formal_subprogram_declaration that has an explicit null_exclusion: 8.2/2 * if the actual matching the formal_subprogram_declaration denotes a generic formal object of another generic unit G, and the instantiation containing the actual that occurs within the body of a generic unit G or within the body of a generic unit declared within the declarative region of the generic unit G, then the corresponding parameter or result type of the formal subprogram of G shall have a null_exclusion; 8.3/2 * otherwise, the subtype of the corresponding parameter or result type of the actual matching the formal_subprogram_declaration shall exclude null. In addition to the places where Legality Rules normally apply (see 12.3), this rule applies also in the private part of an instance of a generic unit. 8.a/2 Reason: This rule prevents "lying". Null must never be the value of a parameter or result with an explicit null_exclusion. The first bullet is an assume-the-worst rule which prevents trouble in generic bodies (including bodies of child generics) when the formal subtype excludes null implicitly. 8.4/3 {AI95-00260-02} {AI05-0296-1} If a formal parameter of a formal_abstract_- subprogram_declaration is of a specific tagged type T or of an anonymous access type designating a specific tagged type T, T is called a controlling type of the formal_abstract_subprogram_declaration. Similarly, if the result of a formal_abstract_subprogram_declaration for a function is of a specific tagged type T or of an anonymous access type designating a specific tagged type T, T is called a controlling type of the formal_abstract_subprogram_- declaration. A formal_abstract_subprogram_declaration shall have exactly one controlling type, and that type shall not be incomplete. 8.b/2 Ramification: The specific tagged type could be any of a formal tagged private type, a formal derived type, a formal interface type, or a normal tagged type. While the last case doesn't seem to be very useful, there isn't any good reason for disallowing it. This rule ensures that the operation is a dispatching operation of some type, and that we unambiguously know what that type is. 8.c/2 We informally call a subprogram declared by a formal_abstract_- subprogram_declaration an abstract formal subprogram, but we do not use this term in normative wording. (We do use it often in these notes.) 8.5/2 {AI95-00260-02} The actual subprogram for a formal_abstract_subprogram_- declaration shall be a dispatching operation of the controlling type or of the actual type corresponding to the controlling type. 8.d/2 To be honest: We mean the controlling type of the formal_abstract_- subprogram_declaration, of course. Saying that gets unwieldy and redundant (so says at least one reviewer, anyway). 8.e/2 Ramification: This means that the actual is either a primitive operation of the controlling type, or an abstract formal subprogram. Also note that this prevents the controlling type from being class-wide (with one exception explained below), as only specific types have primitive operations (and a formal subprogram eventually has to have an actual that is a primitive of some type). This could happen in a case like: 8.f/2 generic type T(<>) is tagged private; with procedure Foo (Obj : in T) is abstract; package P ... 8.g/2 package New_P is new P (Something'Class, Some_Proc); 8.h/2 The instantiation here is always illegal, because Some_Proc could never be a primitive operation of Something'Class (there are no such operations). That's good, because we want calls to Foo always to be dispatching calls. 8.i/2 Since it is possible for a formal tagged type to be instantiated with a class-wide type, it is possible for the (real) controlling type to be class-wide in one unusual case: 8.j/2 generic type NT(<>) is new T with private; -- Presume that T has the following primitive operation: -- with procedure Bar (Obj : in T); package Gr ... 8.k/2 package body Gr is package New_P2 is new P (NT, Foo => Bar); end Gr; 8.l/2 package New_Gr is new Gr (Something'Class); 8.m/2 The instantiation of New_P2 is legal, since Bar is a dispatching operation of the actual type of the controlling type of the abstract formal subprogram Foo. This is not a problem, since the rules given in 12.5.1 explain how this routine dispatches even though its parameter is class-wide. 8.n/2 Note that this legality rule never needs to be rechecked in an instance (that contains a nested instantiation). The rule only talks about the actual type of the instantiation; it does not require looking further; if the actual type is in fact a formal type, we do not intend looking at the actual for that formal. Static Semantics 9 A formal_subprogram_declaration declares a generic formal subprogram. The types of the formal parameters and result, if any, of the formal subprogram are those determined by the subtype_marks given in the formal_subprogram_declaration; however, independent of the particular subtypes that are denoted by the subtype_marks, the nominal subtypes of the formal parameters and result, if any, are defined to be nonstatic, and unconstrained if of an array type [(no applicable index constraint is provided in a call on a formal subprogram)]. In an instance, a formal_subprogram_declaration declares a view of the actual. The profile of this view takes its subtypes and calling convention from the original profile of the actual entity, while taking the formal parameter names and default_expressions from the profile given in the formal_subprogram_declaration. The view is a function or procedure, never an entry. 9.a Discussion: This rule is intended to be the same as the one for renamings-as-declarations, where the formal_subprogram_declaration is analogous to a renaming-as-declaration, and the actual is analogous to the renamed view. 9.1/3 {AI05-0071-1} {AI05-0131-1} If a subtype_mark in the profile of the formal_subprogram_declaration denotes a formal private or formal derived type and the actual type for this formal type is a class-wide type T'Class, then for the purposes of resolving the corresponding actual subprogram at the point of the instantiation, certain implicit declarations may be available as possible resolutions as follows: 9.2/3 For each primitive subprogram of T that is directly visible at the point of the instantiation, and that has at least one controlling formal parameter, a corresponding implicitly declared subprogram with the same defining name, and having the same profile as the primitive subprogram except that T is systematically replaced by T'Class in the types of its profile, is potentially use-visible. The body of such a subprogram is as defined in 12.5.1 for primitive subprograms of a formal type when the actual type is class-wide. 9.b/3 Reason: {AI05-0071-1} {AI05-0131-1} This gives the same capabilities to formal subprograms as those that primitive operations of the formal type have when the actual type is class-wide. We do not want to discourage the use of explicit declarations for (formal) subprograms! 9.c/3 Implementation Note: {AI05-0071-1} {AI05-0131-1} Although the above wording seems to require constructing implicit versions of all of the primitive subprograms of type T, it should be clear that a compiler only needs to consider those that could possibly resolve to the corresponding actual subprogram. For instance, if the formal subprogram is a procedure with two parameters, and the actual subprogram name is Bar (either given explicitly or by default), the compiler need not consider primitives that are functions, that have the wrong number of parameters, that have defining names other than Bar, and so on; thus it does not need to construct implicit declarations for those primitives. 9.d/3 Ramification: {AI05-0071-1} {AI05-0131-1} Functions that only have a controlling result and do not have a controlling parameter of T are not covered by this rule, as any call would be required to raise Program_Error by 12.5.1. It is better to detect the error earlier than at run time. 10 If a generic unit has a subprogram_default specified by a box, and the corresponding actual parameter is omitted, then it is equivalent to an explicit actual parameter that is a usage name identical to the defining name of the formal. 10.1/2 {AI95-00348-01} If a generic unit has a subprogram_default specified by the reserved word null, and the corresponding actual parameter is omitted, then it is equivalent to an explicit actual parameter that is a null procedure having the profile given in the formal_subprogram_declaration. 10.2/2 {AI95-00260-02} The subprogram declared by a formal_abstract_subprogram_- declaration with a controlling type T is a dispatching operation of type T. 10.a/2 Reason: This is necessary to trigger all of the dispatching operation rules. It otherwise would not be considered a dispatching operation, as formal subprograms are never primitive operations. NOTES 11 13 The matching rules for formal subprograms state requirements that are similar to those applying to subprogram_renaming_declarations (see 8.5.4). In particular, the name of a parameter of the formal subprogram need not be the same as that of the corresponding parameter of the actual subprogram; similarly, for these parameters, default_expressions need not correspond. 12 14 The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding subtype_mark in the _specification of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram. 13 15 The subtype specified for a formal parameter of a generic formal subprogram can be any visible subtype, including a generic formal subtype of the same generic_formal_part. 14 16 A formal subprogram is matched by an attribute of a type if the attribute is a function with a matching specification. An enumeration literal of a given type matches a parameterless formal function whose result type is the given type. 15 17 A default_name denotes an entity that is visible or directly visible at the place of the generic_declaration; a box used as a default is equivalent to a name that denotes an entity that is directly visible at the place of the _instantiation. 15.a Proof: Visibility and name resolution are applied to the equivalent explicit actual parameter. 16/2 18 {AI95-00260-02} The actual subprogram cannot be abstract unless the formal subprogram is a formal_abstract_subprogram_declaration (see 3.9.3). 16.1/2 19 {AI95-00260-02} The subprogram declared by a formal_abstract_- subprogram_declaration is an abstract subprogram. All calls on a subprogram declared by a formal_abstract_subprogram_declaration must be dispatching calls. See 3.9.3. 16.2/2 20 {AI95-00348-01} A null procedure as a subprogram default has convention Intrinsic (see 6.3.1). 16.a.1/2 Proof: This is an implicitly declared subprogram, so it has convention Intrinsic as defined in 6.3.1. Examples 17 Examples of generic formal subprograms: 18/2 {AI95-00433-01} with function "+"(X, Y : Item) return Item is <>; with function Image(X : Enum) return String is Enum'Image; with procedure Update is Default_Update; with procedure Pre_Action(X : in Item) is null; -- defaults to no action with procedure Write(S : not null access Root_Stream_Type'Class; Desc : Descriptor) is abstract Descriptor'Write; -- see 13.13.2 -- Dispatching operation on Descriptor with default 19 -- given the generic procedure declaration 20 generic with procedure Action (X : in Item); procedure Iterate(Seq : in Item_Sequence); 21 -- and the procedure 22 procedure Put_Item(X : in Item); 23 -- the following instantiation is possible 24 procedure Put_List is new Iterate(Action => Put_Item); Extensions to Ada 95 24.a/2 {AI95-00260-02} The formal_abstract_subprogram_declaration is new. It allows the passing of dispatching operations to generic units. 24.b/2 {AI95-00348-01} The formal subprogram default of null is new. It allows the default of a generic procedure to do nothing, such as for passing a debugging routine. Wording Changes from Ada 95 24.c/2 {AI95-00423-01} Added matching rules for null_exclusions. Incompatibilities With Ada 2005 24.d/3 {AI05-0296-1} It is now illegal to declare a formal abstract subprogram whose controlling type is incomplete. It was never intended to allow that, and such a type would have to come from outside of the generic unit in Ada 2005, so it is unlikely to be useful. Moreover, a dispatching call on the subprogram is likely to fail in many implementations. So it is very unlikely that any code will need to be changed because of this new rule. Extensions to Ada 2005 24.e/3 {AI05-0071-1} {AI05-0131-1} Correction: Added construction of implicit subprograms for primitives of class-wide actual types, to make it possible to import subprograms via formal subprograms as well as by implicit primitive operations of a formal type. (This is a Correction as it is very important for the usability of indefinite containers when instantiated with class-wide types; thus we want Ada 2005 implementations to support it.) 24.f/3 {AI05-0183-1} An optional aspect_specification can be used in a formal_concrete_subprogram_declaration and a formal_abstract_subprogram_declaration. This is described in 13.1.1. 12.7 Formal Packages 1 [ Formal packages can be used to pass packages to a generic unit. The formal_package_declaration declares that the formal package is an instance of a given generic package. Upon instantiation, the actual package has to be an instance of that generic package.] Syntax 2/3 {AI05-0183-1} formal_package_declaration ::= with package defining_identifier is new generic_package_name formal_package_actual_part [aspect_specification]; 3/2 {AI95-00317-01} formal_package_actual_part ::= ([others =>] <>) | [generic_actual_part] | (formal_package_association {, formal_package_association } [, others => <>]) 3.1/2 {AI95-00317-01} formal_package_association ::= generic_association | generic_formal_parameter_selector_name => <> 3.2/2 {AI95-00317-01} Any positional formal_package_associations shall precede any named formal_package_associations. Legality Rules 4 The generic_package_name shall denote a generic package (the template for the formal package); the formal package is an instance of the template. 4.1/3 {AI05-0025-1} The generic_formal_parameter_selector_name of a formal_package_association shall denote a generic_formal_parameter_declaration of the template. If two or more formal subprograms of the template have the same defining name, then named associations are not allowed for the corresponding actuals. 4.2/3 {AI95-00398-01} A formal_package_actual_part shall contain at most one formal_package_association for each formal parameter. If the formal_package_actual_part does not include "others => <>", each formal parameter without an association shall have a default_expression or subprogram_default. 4.3/3 {AI05-0200-1} The rules for matching between formal_package_associations and the generic formals of the template are as follows: 4.4/3 * If all of the formal_package_associations are given by generic associations, the explicit_generic_actual_parameters of the formal_package_associations shall be legal for an instantiation of the template. 4.5/3 * If a formal_package_association for a formal type T of the template is given by <>, then the formal_package_association for any other generic_formal_parameter_declaration of the template that mentions T directly or indirectly must be given by <> as well. 4.a/3 Discussion: {AI05-0200-1} The above rule is simple to state, though it does not reflect the fact that the formal package functions like an instantiation of a special kind, where each box association for a generic_formal_parameter_declaration F is replaced with a new entity F' that has the same characteristics as F: if F is a formal discrete type then F' is a discrete type, if F is a formal subprogram then F' is a subprogram with a similar signature, etc. In practice this is achieved by making the association into a copy of the declaration of the generic formal. 5/2 {AI95-00317-01} The actual shall be an instance of the template. If the formal_package_actual_part is (<>) or (others => <>), [then the actual may be any instance of the template]; otherwise, certain of the actual parameters of the actual instance shall match the corresponding actual parameters of the formal package, determined as follows: 5.1/2 * {AI95-00317-01} If the formal_package_actual_part includes generic_associations as well as associations with <>, then only the actual parameters specified explicitly with generic_associations are required to match; 5.2/2 * {AI95-00317-01} Otherwise, all actual parameters shall match[, whether any actual parameter is given explicitly or by default]. 5.3/2 {AI95-00317-01} The rules for matching of actual parameters between the actual instance and the formal package are as follows: 6/2 * {AI95-00317-01} For a formal object of mode in, the actuals match if they are static expressions with the same value, or if they statically denote the same constant, or if they are both the literal null. 6.a Reason: We can't simply require full conformance between the two actual parameter expressions, because the two expressions are being evaluated at different times. 7 * For a formal subtype, the actuals match if they denote statically matching subtypes. 8 * For other kinds of formals, the actuals match if they statically denote the same entity. 8.1/1 {8652/0039} {AI95-00213-01} For the purposes of matching, any actual parameter that is the name of a formal object of mode in is replaced by the formal object's actual expression (recursively). Static Semantics 9 A formal_package_declaration declares a generic formal package. 10/2 {AI95-00317-01} The visible part of a formal package includes the first list of basic_declarative_items of the package_specification. In addition, for each actual parameter that is not required to match, a copy of the declaration of the corresponding formal parameter of the template is included in the visible part of the formal package. If the copied declaration is for a formal type, copies of the implicit declarations of the primitive subprograms of the formal type are also included in the visible part of the formal package. 10.a/2 Ramification: {AI95-00317-01} If the formal_package_actual_part is (<>), then the declarations that occur immediately within the generic_formal_part of the template for the formal package are visible outside the formal package, and can be denoted by expanded names outside the formal package.If only some of the actual parameters are given by <>, then the declaration corresponding to those parameters (but not the others) are made visible. 10.b/3 Reason: {AI05-0005-1} We always want either the actuals or the formals of an instance to be nameable from outside, but never both. If both were nameable, one would get some funny anomalies since they denote the same entity, but, in the case of types at least, they might have different and inconsistent sets of primitive operators due to predefined operator "reemergence." Formal derived types exacerbate the difference. We want the implicit declarations of the generic_formal_part as well as the explicit declarations, so we get operations on the formal types. 10.c Ramification: A generic formal package is a package, and is an instance. Hence, it is possible to pass a generic formal package as an actual to another generic formal package. 11/2 {AI95-00317-01} For the purposes of matching, if the actual instance A is itself a formal package, then the actual parameters of A are those specified explicitly or implicitly in the formal_package_actual_part for A, plus, for those not specified, the copies of the formal parameters of the template included in the visible part of A. Examples 12/2 {AI95-00433-01} Example of a generic package with formal package parameters: 13/2 with Ada.Containers.Ordered_Maps; -- see A.18.6 generic with package Mapping_1 is new Ada.Containers.Ordered_Maps(<>); with package Mapping_2 is new Ada.Containers.Ordered_Maps (Key_Type => Mapping_1.Element_Type, others => <>); package Ordered_Join is -- Provide a "join" between two mappings 14/2 subtype Key_Type is Mapping_1.Key_Type; subtype Element_Type is Mapping_2.Element_Type; 15/2 function Lookup(Key : Key_Type) return Element_Type; 16/2 ... end Ordered_Join; 17/2 {AI95-00433-01} Example of an instantiation of a package with formal packages: 18/2 with Ada.Containers.Ordered_Maps; package Symbol_Package is 19/2 type String_Id is ... 20/2 type Symbol_Info is ... 21/2 package String_Table is new Ada.Containers.Ordered_Maps (Key_Type => String, Element_Type => String_Id); 22/2 package Symbol_Table is new Ada.Containers.Ordered_Maps (Key_Type => String_Id, Element_Type => Symbol_Info); 23/2 package String_Info is new Ordered_Join(Mapping_1 => String_Table, Mapping_2 => Symbol_Table); 24/2 Apple_Info : constant Symbol_Info := String_Info.Lookup("Apple"); 25/2 end Symbol_Package; Extensions to Ada 83 25.a Formal packages are new to Ada 95. Extensions to Ada 95 25.b/2 {AI95-00317-01} {AI95-00398-01} It's now allowed to mix actuals of a formal package that are specified with those that are not specified. Wording Changes from Ada 95 25.c/2 {8652/0039} {AI95-00213-01} Corrigendum: Corrected the description of formal package matching to say that formal parameters are always replaced by their actual parameters (recursively). This matches the actual practice of compilers, as the ACATS has always required this behavior. 25.d/2 {AI95-00317-01} The description of which operations are visible in a formal package has been clarified. We also specify how matching is done when the actual is a formal package. Incompatibilities With Ada 2005 25.e/3 {AI05-0025-1} {AI05-0200-1} Correction: Added missing rules for parameters of generic formal package that parallel those in 12.3, as well as some specific to <> parameters. These are technically incompatibilities because generic formal package parameters that Ada 95 and Ada 2005 would have considered legal now have to be rejected. But this should not be an issue in practice as such formal parameters could not have matched any actual generics. And it is quite likely that implementations already enforce some of these rules. Extensions to Ada 2005 25.f/3 {AI05-0183-1} An optional aspect_specification can be used in a formal_package_declaration. This is described in 13.1.1. 12.8 Example of a Generic Package 1 The following example provides a possible formulation of stacks by means of a generic package. The size of each stack and the type of the stack elements are provided as generic formal parameters. Examples 2/1 This paragraph was deleted. 3 generic Size : Positive; type Item is private; package Stack is procedure Push(E : in Item); procedure Pop (E : out Item); Overflow, Underflow : exception; end Stack; 4 package body Stack is 5 type Table is array (Positive range <>) of Item; Space : Table(1 .. Size); Index : Natural := 0; 6 procedure Push(E : in Item) is begin if Index >= Size then raise Overflow; end if; Index := Index + 1; Space(Index) := E; end Push; 7 procedure Pop(E : out Item) is begin if Index = 0 then raise Underflow; end if; E := Space(Index); Index := Index - 1; end Pop; 8 end Stack; 9 Instances of this generic package can be obtained as follows: 10 package Stack_Int is new Stack(Size => 200, Item => Integer); package Stack_Bool is new Stack(100, Boolean); 11 Thereafter, the procedures of the instantiated packages can be called as follows: 12 Stack_Int.Push(N); Stack_Bool.Push(True); 13 Alternatively, a generic formulation of the type Stack can be given as follows (package body omitted): 14 generic type Item is private; package On_Stacks is type Stack(Size : Positive) is limited private; procedure Push(S : in out Stack; E : in Item); procedure Pop (S : in out Stack; E : out Item); Overflow, Underflow : exception; private type Table is array (Positive range <>) of Item; type Stack(Size : Positive) is record Space : Table(1 .. Size); Index : Natural := 0; end record; end On_Stacks; 15 In order to use such a package, an instance has to be created and thereafter stacks of the corresponding type can be declared: 16 declare package Stack_Real is new On_Stacks(Real); use Stack_Real; S : Stack(100); begin ... Push(S, 2.54); ... end;