Skip to main content

12.4 Formal Objects

danger

This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue

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 
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

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

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
  • 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
  • shall both be access-to-subprogram types with subtype conformant designated profiles.
8.3/5

For a formal_object_declaration of mode in out with a null_exclusion or an access_definition that has a null_exclusion, the subtype of the actual matching the formal_object_declaration shall exclude null. In addition, if the actual matching the formal_object_declaration statically denotes the generic formal object of mode in out 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. 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/5
reason

This rule prevents “lying”. Null must never be the value of an object with an explicit null_exclusion. The “in addition” part is an assume-the-worst rule which prevents trouble in generic bodies (including bodies of child units) when the subtype of the formal object of mode in out excludes null implicitly. Since a generic formal object of mode in is like a constant initialized to the value of the actual, the runtime check performed by the initialization is enough to prevent lying; thus we don't need a Legality Rule for such objects.

Static Semantics​

9/2

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

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

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

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

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.

12

NOTE 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

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

A generic formal object can have a null_exclusion or an anonymous access type.

Wording Changes from Ada 95​

12.g/2

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

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

An optional aspect_specification can be used in a formal_object_declaration. This is described in 13.1.1.

Extensions to Ada 2012​

12.j/5
correction

The Legality Rule for matching null exclusions only applies to formal objects with mode in out. (In mode formal objects have a run-time check to avoid problems.) This is an extension as some instantiations that were illegal in original Ada 2012 are now legal.