12.1. Generic Declarations

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 or a subprogram.

    generic_declaration ::= generic_specification; 

    generic_specification ::=
         generic_formal_part subprogram_specification
       | generic_formal_part package_specification 

    generic_formal_part ::= generic {generic_parameter_declaration} 

    generic_parameter_declaration ::=
         identifier_list : [in [out]] type_mark [:= expression];  
       | type identifier is generic_type_definition;
       | private_type_declaration
       | with subprogram_specification [is name];
       | with subprogram_specification [is <>]; 

    generic_type_definition ::=
         (<>) | range <> | digits <> | delta <>
       | array_type_definition | access_type_definition                           

The terms generic formal object (or simply, formal object), generic formal type (or simply, formal type), and generic formal subprogram (or simply, formal subprogram) are used to refer to corresponding generic formal parameters.

The only form of subtype indication allowed within a generic formal part is a type mark (that is, the subtype indication must not include an explicit constraint). The designator of a generic subprogram must be an identifier.

Outside the specification and body of a generic unit, the name of this program unit denotes the generic unit. In contrast, within the declarative region associated with a generic subprogram, the name of this program unit denotes the subprogram obtained by the current instantiation of the generic unit. Similarly, within the declarative region associated with a generic package, the name of this program unit denotes the package obtained by the current instantiation.

The elaboration of a generic declaration has no other effect.

Examples of generic formal parts:

    generic     --  parameterless 

    generic
       SIZE : NATURAL;  --  formal object 

    generic
       LENGTH : INTEGER := 200;          -- formal object with a default
                                            expression
       AREA   : INTEGER := LENGTH*LENGTH; -- formal object with a default
                                             expression

    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 

Examples of generic declarations declaring generic subprograms:

    generic
       type ELEM is private;
    procedure EXCHANGE(U, V : in out ELEM); 

    generic
       type ITEM is private;
       with function "*"(U, V : ITEM) return ITEM is <>;
    function SQUARING(X : ITEM) return ITEM; 

Example of a generic declaration declaring a generic package:

    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;                                                                      

Notes:

Within a generic subprogram, 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 instantiation. For the same reason, this name cannot appear after the reserved word new in a (recursive) generic instantiation.

An expression that occurs in a generic formal part is either the default expression for a generic formal object of mode in, or a constituent of an entry name given as default name for a formal subprogram, or the default expression for a parameter of a formal subprogram. Default expressions for generic formal objects and default names for formal subprograms are only evaluated for generic instantiations that use such defaults. Default expressions for parameters of formal subprograms are only evaluated for calls of the formal subprograms that use such defaults. (The usual visibility rules apply to any name used in a default expression: the denoted entity must therefore be visible at the place of the expression.)

Neither generic formal parameters nor their attributes are allowed constituents of static expressions (see 4.9).

References: access type definition, array type definition, attribute, constraint, declaration, designator, elaboration has no other effect, entity, expression, function, generic instantiation, identifier, identifier list, instance, name, object, overloading, and 8.7, package specification, parameter of a subprogram, private type definition, procedure, reserved word, static expression, subprogram, subprogram specification, subtype indication, type, type mark.

Sub-topics:

• 12.1.1 Generic Formal Objects
• 12.1.2 Generic Formal Types
• 12.1.3 Generic Formal Subprograms

12.1.1. Generic Formal Objects

The first form of generic parameter declaration declares generic formal objects. The type of a generic formal object is the base type of the type denoted by the type mark given in the generic parameter declaration. A generic parameter declaration with several identifiers is equivalent to a sequence of single generic parameter declarations, as explained in section 3.2.

A generic formal object has a mode that is either in or in out. In the absence of an explicit mode indication in a generic parameter declaration, the mode in is assumed; otherwise the mode is the one indicated. If a generic parameter declaration ends with an expression, the expression is the default expression of the generic formal parameter. A default expression is only allowed if the mode is in (whether this mode is indicated explicitly or implicitly). The type of a default expression must be that of the corresponding generic formal parameter.

A generic formal object of mode in is a constant whose value is a copy of the value supplied as the matching generic actual parameter in a generic instantiation, as described in section 12.3. The type of a generic formal object of mode in must not be a limited type; the subtype of such a generic formal object is the subtype denoted by the type mark given in the generic parameter declaration.

A generic formal object of mode in out is a variable and denotes the object supplied as the matching generic actual parameter in a generic instantiation, as described in section 12.3. The constraints that apply to the generic formal object are those of the corresponding generic actual parameter.

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 type mark that appears in the generic parameter declaration). Whenever possible (to avoid confusion) it is recommended that the name of a base type be used for the declaration of such a formal object. If, however, the base type is anonymous, it is recommended that the subtype name defined by the type declaration for the base type be used.

References: anonymous type, assignment, base type, constant declaration, constraint, declaration, generic actual parameter, generic formal object, generic formal parameter, generic instantiation, generic parameter declaration, identifier, limited type, matching generic actual parameter, mode, name, object, simple name, subtype, type declaration, type mark, variable.

12.1.2. Generic Formal Types

A generic parameter declaration that includes a generic type definition or a private type declaration declares a generic formal type. A generic formal type denotes the subtype supplied as the corresponding actual parameter in a generic instantiation, as described in 12.3(d). However, within a generic unit, a generic formal type is considered as being distinct from all other (formal or nonformal) types. The form of constraint applicable to a formal type in a subtype indication depends on the class of the type as for a nonformal type.

The only form of discrete range that is allowed within the declaration of a generic formal (constrained) array type is a type mark.

The discriminant part of a generic formal private type must not include a default expression for a discriminant. (Consequently, a variable that is declared by an object declaration must be constrained if its type is a generic formal type with discriminants.)

Within the declaration and body of a generic unit, the operations available for values of a generic formal type (apart from any additional operation specified by a generic formal subprogram) are determined by the generic parameter declaration for the formal type:

1. For a private type declaration, the available operations are those defined in section 7.4.2 (in particular, assignment, equality, and inequality are available for a private type unless it is limited).

2. For an array type definition, the available operations are those defined in section 3.6.2 (for example, they include the formation of indexed components and slices).

3. For an access type definition, the available operations are those defined in section 3.8.2 (for example, allocators can be used).

1. Discrete types: (<>)

   The available operations are the operations common to enumeration and integer types; these are defined in section 3.5.5.

2. Integer types: range <>

   The available operations are the operations of integer types defined in section 3.5.5.

3. Floating point types: digits <>

   The available operations are those defined in section 3.5.8.

4. Fixed point types: delta <>

   The available operations are those defined in section 3.5.10.

For an instantiation of the generic unit, each of these operations is the corresponding basic operation or predefined operator of the matching actual type. For an operator, this rule applies even if the operator has been redefined for the actual type or for some parent type of the actual type.

Examples of generic formal types:

    type ITEM is private;
    type BUFFER(LENGTH : NATURAL) is limited private; 

    type ENUM  is (<>);
    type INT   is range <>;
    type ANGLE is delta <>;
    type MASS  is digits <>; 

    type TABLE is array (ENUM) of ITEM;  

Example of a generic formal part declaring a formal integer type:

    generic
       type RANK is range <>;
       FIRST  : RANK := RANK'FIRST;
       SECOND : RANK := FIRST + 1;  --  the operator "+" of the type RANK  

References: access type definition, allocator, array type definition, assignment, body of a generic unit, class of type, constraint, declaration, declaration of a generic unit, discrete range, discrete type, discriminant part, enumeration type, equality, fixed point type, floating point type, generic actual type, generic formal part, generic formal subprogram, generic formal type, generic parameter declaration, generic type definition, indexed component, inequality, instantiation, integer type, limited private type, matching generic actual type, and 12.3.3, and 12.3.4, and 12.3.5, multiplying operator, and 4.5.5, operation, operator, parent type, 8.6, subtype indication, type mark, universal_fixed.

12.1.3. Generic Formal Subprograms

A generic parameter declaration that includes a subprogram specification declares a generic formal subprogram.

Two alternative forms of defaults can be specified in the declaration of a generic formal subprogram. In these forms, the subprogram specification is followed by the reserved word is and either a box or the name of a subprogram or entry. The matching rules for these defaults are explained in section 12.3.6.

A generic formal subprogram denotes the subprogram, enumeration literal, or entry supplied as the corresponding generic actual parameter in a generic instantiation, as described in section 12.3(f).

Examples of generic formal subprograms:

    with function INCREASE(X : INTEGER) return INTEGER;
    with function SUM(X, Y : ITEM) return ITEM; 

    with function "+"(X, Y : ITEM) return ITEM is <>;
    with function IMAGE(X : ENUM) return STRING is ENUM'IMAGE; 

    with procedure UPDATE is DEFAULT_UPDATE; 

Notes:

The constraints that apply to a parameter of a formal subprogram are those of the corresponding parameter in the specification of the matching actual subprogram (not those implied by the corresponding type mark in the specification of the formal subprogram). A similar remark applies to the result of a function. Whenever possible (to avoid confusion), it is recommended that the name of a base type be used rather than the name of a subtype in any declaration of a formal subprogram. If, however, the base type is anonymous, it is recommended that the subtype name defined by the type declaration be used.

The type specified for a formal parameter of a generic formal subprogram can be any visible type, including a generic formal type of the same generic formal part.

References: anonymous type, base type, box delimiter, constraint, designator, generic actual parameter, generic formal function, generic formal subprogram, generic instantiation, generic parameter declaration, identifier, matching generic actual subprogram, operator symbol, parameter of a subprogram, renaming declaration, reserved word, scope, subprogram, subprogram specification, subtype, type, type mark.