Subprograms

1. A subprogram is a program unit or intrinsic operation whose execution is invoked by a subprogram call. There are two forms of subprogram: procedures and functions. A procedure call is a statement; a function call is an expression and returns a value. The definition of a subprogram can be given in two parts: a subprogram declaration defining its interface, and a subprogram_body defining its execution. Operators and enumeration literals are functions.
2. A callable entity is a subprogram or entry, see section Tasks and Synchronization. A callable entity is invoked by a call; that is, a subprogram call or entry call. A callable construct is a construct that defines the action of a call upon a callable entity: a subprogram_body, entry_body, or accept_statement.

Subprogram Declarations

1. A subprogram_declaration declares a procedure or function. Syntax

2. subprogram_declaration ::= subprogram_specification;
   

3. abstract_subprogram_declaration ::=
      subprogram_specification is abstract;
   

4. subprogram_specification ::=
        procedure defining_program_unit_name parameter_profile
      | function defining_designator parameter_and_result_profile
   

5. designator ::= [parent_unit_name . ]identifier | operator_symbol
   

6. defining_designator ::=
      defining_program_unit_name | defining_operator_symbol
   

7. defining_program_unit_name ::=
      [parent_unit_name . ]defining_identifier
   

   1. The optional parent_unit_name is only allowed for library units, See section Compilation Units - Library Units.

1. operator_symbol ::= string_literal
   

   1. The sequence of characters in an operator_symbol shall correspond to an operator belonging to one of the six classes of operators defined in clause section Operators and Expression Evaluation (spaces are not allowed and the case of letters is not significant).

1. defining_operator_symbol ::= operator_symbol
   

2. parameter_profile ::= [formal_part]
   

3. parameter_and_result_profile ::= [formal_part] return subtype_mark
   

4. formal_part ::=
      (parameter_specification {; parameter_specification{)
   

5. parameter_specification ::=
       defining_identifier_list : mode subtype_mark
         [:= default_expression]
     | defining_identifier_list : access_definition
         [:= default_expression]
   

6. mode ::= [in] | in out | out
   

   Name Resolution Rules
7. A formal parameter is an object directly visible within a subprogram_body that represents the actual parameter passed to the subprogram in a call; it is declared by a parameter_specification. For a formal parameter, the expected type for its default_expression, if any, is that of the formal parameter. Legality Rules
8. The parameter mode of a formal parameter conveys the direction of information transfer with the actual parameter: in, in out, or out. Mode in is the default, and is the mode of a parameter defined by an access_definition. The formal parameters of a function, if any, shall have the mode in.
9. A default_expression is only allowed in a parameter_specification for a formal parameter of mode in.
10. A subprogram_declaration or a generic_subprogram_declaration requires a completion: a body, a renaming_declaration, see section Renaming Declarations, or a pragma Import, see section Interfacing Pragmas. A completion is not allowed for an abstract_subprogram_declaration.
11. A name that denotes a formal parameter is not allowed within the formal_part in which it is declared, nor within the formal_part of a corresponding body or accept_statement. Static Semantics
12. The profile of (a view of) a callable entity is either a parameter_profile or parameter_and_result_profile; it embodies information about the interface to that entity -- for example, the profile includes information about parameters passed to the callable entity. All callable entities have a profile -- enumeration literals, other subprograms, and entries. An access-to-subprogram type has a designated profile. Associated with a profile is a calling convention. A subprogram_declaration declares a procedure or a function, as indicated by the initial reserved word, with name and profile as given by its specification.
13. The nominal subtype of a formal parameter is the subtype denoted by the subtype_mark, or defined by the access_definition, in the parameter_specification.
14. An access parameter is a formal in parameter specified by an access_definition. An access parameter is of an anonymous general access-to-variable type, see section Access Types. Access parameters allow dispatching calls to be controlled by access values.
15. The subtypes of a profile are:
    1. For any non-access parameters, the nominal subtype of the parameter.
    2. For any access parameters, the designated subtype of the parameter type.
    3. For any result, the result subtype.

1. The types of a profile are the types of those subtypes.
2. A subprogram declared by an abstract_subprogram_declaration is abstract; a subprogram declared by a subprogram_declaration is not. See section Abstract Types and Subprograms. Dynamic Semantics
3. The elaboration of a subprogram_declaration or an abstract_subprogram_declaration has no effect. NOTES
4. (1) A parameter_specification with several identifiers is equivalent to a sequence of single parameter_specifications, as explained in 3.3.
5. (2) Abstract subprograms do not have bodies, and cannot be used in a nondispatching call, see section Abstract Types and Subprograms.
6. (3) The evaluation of default_expressions is caused by certain calls, as described in section Parameter Associations. They are not evaluated during the elaboration of the subprogram declaration.
7. (4) Subprograms can be called recursively and can be called concurrently from multiple tasks. Examples
8. Examples of subprogram declarations:

9. procedure Traverse_Tree;
   procedure Increment(X : in out Integer);
   procedure Right_Indent(Margin : out Line_Size); --  see section Integer Types
   procedure Switch(From, To : in out Link);       --  see section Incomplete Type Declarations
   

10. function Random return Probability;             --  see section Floating Point Types
    

11. function Min_Cell(X : Link) return Cell;        --  see section Incomplete Type Declarations
    function Next_Frame(K : Positive) return Frame; --  see section Access Types
    function Dot_Product(Left, Right : Vector) return Real;
    --  see section Array Types
    

12. function "*"(Left, Right : Matrix) return Matrix;
    --  see section Array Types
    

13. Examples of in parameters with default expressions:

14. procedure Print_Header
      (Pages  : in Natural;
       Header : in Line    :=  (1 .. Line'Last => ' '); --  see section Array Types
       Center : in Boolean := True);
    

Formal Parameter Modes

1. A parameter_specification declares a formal parameter of mode in, in out, or out. Static Semantics
2. A parameter is passed either by copy or by reference. When a parameter is passed by copy, the formal parameter denotes a separate object from the actual parameter, and any information transfer between the two occurs only before and after executing the subprogram. When a parameter is passed by reference, the formal parameter denotes (a view of) the object denoted by the actual parameter; reads and updates of the formal parameter directly reference the actual parameter object.
3. A type is a by-copy type if it is an elementary type, or if it is a descendant of a private type whose full type is a by-copy type. A parameter of a by-copy type is passed by copy.
4. A type is a by-reference type if it is a descendant of one of the following:
   1. a tagged type;
   2. a task or protected type;
   3. a nonprivate type with the reserved word limited in its declaration;
   4. a composite type with a subcomponent of a by-reference type;
   5. a private type whose full type is a by-reference type.

1. A parameter of a by-reference type is passed by reference. Each value of a by-reference type has an associated object. For a parenthesized expression, qualified_expression, or type_conversion, this object is the one associated with the operand.
2. For parameters of other types, it is unspecified whether the parameter is passed by copy or by reference. Bounded (Run-Time) Errors
3. If one name denotes a part of a formal parameter, and a second name denotes a part of a distinct formal parameter or an object that is not part of a formal parameter, then the two names are considered distinct access paths. If an object is of a type for which the parameter passing mechanism is not specified, then it is a bounded error to assign to the object via one access path, and then read the value of the object via a distinct access path, unless the first access path denotes a part of a formal parameter that no longer exists at the point of the second access (due to leaving the corresponding callable construct). The possible consequences are that Program_Error is raised, or the newly assigned value is read, or some old value of the object is read. NOTES
4. (5) A formal parameter of mode in is a constant view, see section Objects and Named Numbers, it cannot be updated within the subprogram_body.

Subprogram Bodies

1. A subprogram_body specifies the execution of a subprogram. Syntax

2. subprogram_body ::=
      subprogram_specification is
         declarative_part
      begin
         handled_sequence_of_statements
      end [designator];
   

   1. If a designator appears at the end of a subprogram_body, it shall repeat the defining_designator of the subprogram_specification.

Legality Rules

1. In contrast to other bodies, a subprogram_body need not be the completion of a previous declaration, in which case the body declares the subprogram. If the body is a completion, it shall be the completion of a subprogram_declaration or generic_subprogram_declaration. The profile of a subprogram_body that completes a declaration shall conform fully to that of the declaration. Static Semantics
2. A subprogram_body is considered a declaration. It can either complete a previous declaration, or itself be the initial declaration of the subprogram. Dynamic Semantics
3. The elaboration of a non-generic subprogram_body has no other effect than to establish that the subprogram can from then on be called without failing the Elaboration_Check.
4. The execution of a subprogram_body is invoked by a subprogram call. For this execution the declarative_part is elaborated, and the handled_sequence_of_statements is then executed. Examples
5. Example of procedure body:

6. procedure Push(E : in Element_Type; S : in out Stack) is
   begin
      if S.Index = S.Size then
         raise Stack_Overflow;
      else
         S.Index := S.Index + 1;
         S.Space(S.Index) := E;
      end if;
   end Push;
   

7. Example of a function body:

8. function Dot_Product(Left, Right : Vector) return Real is
      Sum : Real := 0.0;
   begin
      Check(Left'First = Right'First and Left'Last = Right'Last);
      for J in Left'Range loop
         Sum := Sum + Left(J)*Right(J);
      end loop;
      return Sum;
   end Dot_Product;
   

Conformance Rules

1. When subprogram profiles are given in more than one place, they are required to conform in one of four ways: type conformance, mode conformance, subtype conformance, or full conformance. Static Semantics
2. As explained in section Interfacing Pragmas, a convention can be specified for an entity. For a callable entity or access-to-subprogram type, the convention is called the calling convention. The following conventions are defined by the language:
   1. The default calling convention for any subprogram not listed below is Ada. A pragma Convention, Import, or Export may be used to override the default calling convention, see section Interfacing Pragmas.
   2. The Intrinsic calling convention represents subprograms that are "built in" to the compiler. The default calling convention is Intrinsic for the following:
      1. an enumeration literal;
      2. a "/=" operator declared implicitly due to the declaration of "=", See section Overloading of Operators,
      3. any other implicitly declared subprogram unless it is a dispatching operation of a tagged type;
      4. an inherited subprogram of a generic formal tagged type with unknown discriminants;
      5. an attribute that is a subprogram;
      6. a subprogram declared immediately within a protected_body.

1. The Access attribute is not allowed for Intrinsic subprograms.

1. The default calling convention is protected for a protected subprogram, and for an access-to-subprogram type with the reserved word protected in its definition.
2. The default calling convention is entry for an entry.

1. Of these four conventions, only Ada and Intrinsic are allowed as a convention_identifier in a pragma Convention, Import, or Export.
2. Two profiles are type conformant if they have the same number of parameters, and both have a result if either does, and corresponding parameter and result types are the same, or, for access parameters, corresponding designated types are the same.
3. Two profiles are mode conformant if they are type-conformant, and corresponding parameters have identical modes, and, for access parameters, the designated subtypes statically match.
4. Two profiles are subtype conformant if they are mode-conformant, corresponding subtypes of the profile statically match, and the associated calling conventions are the same. The profile of a generic formal subprogram is not subtype-conformant with any other profile.
5. Two profiles are fully conformant if they are subtype-conformant, and corresponding parameters have the same names and have default_expressions that are fully conformant with one another.
6. Two expressions are fully conformant if, after replacing each use of an operator with the equivalent function_call:
   1. each constituent construct of one corresponds to an instance of the same syntactic category in the other, except that an expanded name may correspond to a direct_name (or character_literal) or to a different expanded name in the other; and
   2. each direct_name, character_literal, and selector_name that is not part of the prefix of an expanded name in one denotes the same declaration as the corresponding direct_name, character_literal, or selector_name in the other; and
   3. each primary that is a literal in one has the same value as the corresponding literal in the other.

1. Two known_discriminant_parts are fully conformant if they have the same number of discriminants, and discriminants in the same positions have the same names, statically matching subtypes, and default_expressions that are fully conformant with one another.
2. Two discrete_subtype_definitions are fully conformant if they are both subtype_indications or are both ranges, the subtype_marks (if any) denote the same subtype, and the corresponding simple_expressions of the ranges (if any) fully conform. Implementation Permissions
3. An implementation may declare an operator declared in a language-defined library unit to be intrinsic.

Inline Expansion of Subprograms

1. Subprograms may be expanded in line at the call site. Syntax
2. The form of a pragma Inline, which is a program unit pragma, See section Pragmas and Program Units, is as follows:

3. pragma Inline(name {, name{);
   

   Legality Rules
4. The pragma shall apply to one or more callable entities or generic subprograms. Static Semantics
5. If a pragma Inline applies to a callable entity, this indicates that inline expansion is desired for all calls to that entity. If a pragma Inline applies to a generic subprogram, this indicates that inline expansion is desired for all calls to all instances of that generic subprogram. Implementation Permissions
6. For each call, an implementation is free to follow or to ignore the recommendation expressed by the pragma. NOTES
7. (6) The name in a pragma Inline can denote more than one entity in the case of overloading. Such a pragma applies to all of the denoted entities.

Subprogram Calls

1. A subprogram call is either a procedure_call_statement or a function_call; it invokes the execution of the subprogram_body. The call specifies the association of the actual parameters, if any, with formal parameters of the subprogram. Syntax

2. procedure_call_statement ::=
        procedure_name;
      | procedure_prefix actual_parameter_part;
   

3. function_call ::=
        function_name
      | function_prefix actual_parameter_part
   

4. actual_parameter_part ::=
      (parameter_association {, parameter_association{)
   

5. parameter_association ::=
      [formal_parameter_selector_name =>] explicit_actual_parameter
   

6. explicit_actual_parameter ::= expression | variable_name
   

   1. A parameter_association is named or positional according to whether or not the formal_parameter_selector_name is specified. Any positional associations shall precede any named associations. Named associations are not allowed if the prefix in a subprogram call is an attribute_reference.

Name Resolution Rules

1. The name or prefix given in a procedure_call_statement shall resolve to denote a callable entity that is a procedure, or an entry renamed as (viewed as) a procedure. The name or prefix given in a function_call shall resolve to denote a callable entity that is a function. When there is an actual_parameter_part, the prefix can be an implicit_dereference of an access-to-subprogram value.
2. A subprogram call shall contain at most one association for each formal parameter. Each formal parameter without an association shall have a default_expression (in the profile of the view denoted by the name or prefix). This rule is an overloading rule, see section The Context of Overload Resolution. Dynamic Semantics
3. For the execution of a subprogram call, the name or prefix of the call is evaluated, and each parameter_association is evaluated, see section Parameter Associations. If a default_expression is used, an implicit parameter_association is assumed for this rule. These evaluations are done in an arbitrary order. The subprogram_body is then executed. Finally, if the subprogram completes normally, then after it is left, any necessary assigning back of formal to actual parameters occurs, see section Parameter Associations.
4. The exception Program_Error is raised at the point of a function_call if the function completes normally without executing a return_statement.
5. A function_call denotes a constant, as defined in section Return Statements, the nominal subtype of the constant is given by the result subtype of the function. Examples
6. Examples of procedure calls:

7. Traverse_Tree;                   --  see section Subprogram Declarations
   Print_Header(128, Title, True);  --  see section Subprogram Declarations
   

8. Switch(From => X, To => Next);
   --  see section Subprogram Declarations.
   
   Print_Header(128, Header => Title, Center => True);
   --  see section Subprogram Declarations.
   
   Print_Header(Header => Title, Center => True, Pages => 128);
   --  see section Subprogram Declarations.
   

9. Examples of function calls:

10. Dot_Product(U, V)   --  see section Subprogram Declarations, and section Subprogram Bodies.
    Clock               --  see section Delay Statements, Duration, and Time.
    F.all
    --  presuming F is of an access-to-subprogram type
    --  see section Access Types.
    

11. Examples of procedures with default expressions:

12. procedure Activate(Process : in Process_Name;
                       After   : in Process_Name := No_Process;
                       Wait    : in Duration := 0.0;
                       Prior   : in Boolean := False);
    

13. procedure Pair(Left, Right : in Person_Name := new Person);
    --  see section Incomplete Type Declarations.
    

14. Examples of their calls:

15. Activate(X);
    Activate(X, After => Y);
    Activate(X, Wait => 60.0, Prior => True);
    Activate(X, Y, 10.0, False);
    

16. Pair;
    Pair(Left => new Person, Right => new Person);
    

    NOTES
17. (7) If a default_expression is used for two or more parameters in a multiple parameter_specification, the default_expression is evaluated once for each omitted parameter. Hence in the above examples, the two calls of Pair are equivalent. Examples
18. Examples of overloaded subprograms:

19. procedure Put(X : in Integer);
    procedure Put(X : in String);
    

20. procedure Set(Tint   : in Color);
    procedure Set(Signal : in Light);
    

21. Examples of their calls:

22. Put(28);
    Put("no possible ambiguity here");
    

23. Set(Tint   => Red);
    Set(Signal => Red);
    Set(Color'(Red));
    

24. --  Set(Red) would be ambiguous since Red may
    --  denote a value either of type Color or of type Light
    

Parameter Associations

1. A parameter association defines the association between an actual parameter and a formal parameter. Name Resolution Rules
2. The formal_parameter_selector_name of a parameter_association shall resolve to denote a parameter_specification of the view being called.
3. The actual parameter is either the explicit_actual_parameter given in a parameter_association for a given formal parameter, or the corresponding default_expression if no parameter_association is given for the formal parameter. The expected type for an actual parameter is the type of the corresponding formal parameter.
4. If the mode is in, the actual is interpreted as an expression; otherwise, the actual is interpreted only as a name, if possible. Legality Rules
5. If the mode is in out or out, the actual shall be a name that denotes a variable.
6. The type of the actual parameter associated with an access parameter shall be convertible, see section Type Conversions, to its anonymous access type. Dynamic Semantics
7. For the evaluation of a parameter_association:
   1. The actual parameter is first evaluated.
   2. For an access parameter, the access_definition is elaborated, which creates the anonymous access type.
   3. For a parameter (of any mode) that is passed by reference, see section Formal Parameter Modes, a view conversion of the actual parameter to the nominal subtype of the formal parameter is evaluated, and the formal parameter denotes that conversion.
   4. For an in or in out parameter that is passed by copy, see section Formal Parameter Modes, the formal parameter object is created, and the value of the actual parameter is converted to the nominal subtype of the formal parameter and assigned to the formal.
   5. For an out parameter that is passed by copy, the formal parameter object is created, and:
      1. For an access type, the formal parameter is initialized from the value of the actual, without a constraint check;
      2. For a composite type with discriminants or that has implicit initial values for any subcomponents, see section Object Declarations, the behavior is as for an in out parameter passed by copy.
      3. For any other type, the formal parameter is uninitialized. If composite, a view conversion of the actual parameter to the nominal subtype of the formal is evaluated (which might raise Constraint_Error), and the actual subtype of the formal is that of the view conversion. If elementary, the actual subtype of the formal is given by its nominal subtype.

1. A formal parameter of mode in out or out with discriminants is constrained if either its nominal subtype or the actual parameter is constrained.
2. After normal completion and leaving of a subprogram, for each in out or out parameter that is passed by copy, the value of the formal parameter is converted to the subtype of the variable given as the actual parameter and assigned to it. These conversions and assignments occur in an arbitrary order.

Return Statements

1. A return_statement is used to complete the execution of the innermost enclosing subprogram_body, entry_body, or accept_statement. Syntax

2. return_statement ::= return [expression];
   

   Name Resolution Rules
3. The expression, if any, of a return_statement is called the return expression. The result subtype of a function is the subtype denoted by the subtype_mark after the reserved word return in the profile of the function. The expected type for a return expression is the result type of the corresponding function. Legality Rules
4. A return_statement shall be within a callable construct, and it applies to the innermost one. A return_statement shall not be within a body that is within the construct to which the return_statement applies.
5. A function body shall contain at least one return_statement that applies to the function body, unless the function contains code_statements. A return_statement shall include a return expression if and only if it applies to a function body. Dynamic Semantics
6. For the execution of a return_statement, the expression (if any) is first evaluated and converted to the result subtype.
7. If the result type is class-wide, then the tag of the result is the tag of the value of the expression.
8. If the result type is a specific tagged type:
   1. If it is limited, then a check is made that the tag of the value of the return expression identifies the result type. Constraint_Error is raised if this check fails.
   2. If it is nonlimited, then the tag of the result is that of the result type.

1. A type is a return-by-reference type if it is a descendant of one of the following:
   1. a tagged limited type;
   2. a task or protected type;
   3. a nonprivate type with the reserved word limited in its declaration;
   4. a composite type with a subcomponent of a return-by-reference type;
   5. a private type whose full type is a return-by-reference type.

1. If the result type is a return-by-reference type, then a check is made that the return expression is one of the following:
   1. a name that denotes an object view whose accessibility level is not deeper than that of the master that elaborated the function body; or
   2. a parenthesized expression or qualified_expression whose operand is one of these kinds of expressions.

1. The exception Program_Error is raised if this check fails.
2. For a function with a return-by-reference result type the result is returned by reference; that is, the function call denotes a constant view of the object associated with the value of the return expression. For any other function, the result is returned by copy; that is, the converted value is assigned into an anonymous constant created at the point of the return_statement, and the function call denotes that object.
3. Finally, a transfer of control is performed which completes the execution of the callable construct to which the return_statement applies, and returns to the caller. Examples
4. Examples of return statements:

5. return;
   -- in a procedure body, entry_body, or accept_statement
   
   return Key_Value(Last_Index);
   -- in a function body
   

Overloading of Operators

1. An operator is a function whose designator is an operator_symbol. Operators, like other functions, may be overloaded. Name Resolution Rules
2. Each use of a unary or binary operator is equivalent to a function_call with function_prefix being the corresponding operator_symbol, and with (respectively) one or two positional actual parameters being the operand(s) of the operator (in order). Legality Rules
3. The subprogram_specification of a unary or binary operator shall have one or two parameters, respectively. A generic function instantiation whose designator is an operator_symbol is only allowed if the specification of the generic function has the corresponding number of parameters.
4. Default_expressions are not allowed for the parameters of an operator (whether the operator is declared with an explicit subprogram_specification or by a generic_instantiation).
5. An explicit declaration of "/=" shall not have a result type of the predefined type Boolean. Static Semantics
6. A declaration of "=" whose result type is Boolean implicitly declares a declaration of "/=" that gives the complementary result. NOTES
7. (8) The operators "+" and "-" are both unary and binary operators, and hence may be overloaded with both one- and two-parameter functions. Examples
8. Examples of user-defined operators:

9. function "+" (Left, Right : Matrix) return Matrix;
   function "+" (Left, Right : Vector) return Vector;
   
   --  assuming that A, B, and C are of the type Vector
   --  the following two statements are equivalent:
   
   A := B + C;
   A := "+"(B, C);
   

Go to the first, previous, next, last section, table of contents.