

                           Section 6: 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 9). 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.


6.1 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

8     The optional parent_unit_name is only allowed for library units (see
      10.1.1).

9     operator_symbol ::= string_literal

10    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 4.5 (spaces are not allowed and the case of letters is not
      significant).

11    defining_operator_symbol ::= operator_symbol

12    parameter_profile ::= [formal_part]

13    parameter_and_result_profile ::= [formal_part] return subtype_mark

14    formal_part ::= 
         (parameter_specification {; parameter_specification})

15    parameter_specification ::= 
          defining_identifier_list : mode  subtype_mark
       [:= default_expression]
        | defining_identifier_list : access_definition
       [:= default_expression]

16    mode ::= [in] | in out | out


                            Name Resolution Rules

17    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

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

19    A default_expression is only allowed in a parameter_specification for a
formal parameter of mode in.

20    A subprogram_declaration or a generic_subprogram_declaration requires a
completion: a body, a renaming_declaration (see 8.5), or a pragma Import (see
B.1). A completion is not allowed for an abstract_subprogram_declaration.

21    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

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

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

24    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 3.10). Access parameters allow dispatching calls
to be controlled by access values.

25    The subtypes of a profile are:

26    For any non-access parameters, the nominal subtype of the parameter.

27    For any access parameters, the designated subtype of the parameter type.

28    For any result, the result subtype.

29    The types of a profile are the types of those subtypes.

30    A subprogram declared by an abstract_subprogram_declaration is abstract;
a subprogram declared by a subprogram_declaration is not. See 3.9.3, ``
Abstract Types and Subprograms''.


                              Dynamic Semantics

31    The elaboration of a subprogram_declaration or an
abstract_subprogram_declaration has no effect.

      NOTES

32    1  A parameter_specification with several identifiers is equivalent to a
      sequence of single parameter_specifications, as explained in 3.3.

33    2  Abstract subprograms do not have bodies, and cannot be used in a
      nondispatching call (see 3.9.3, ``Abstract Types and Subprograms'').

34    3  The evaluation of default_expressions is caused by certain calls, as
      described in 6.4.1. They are not evaluated during the elaboration of the
      subprogram declaration.

35    4  Subprograms can be called recursively and can be called concurrently
      from multiple tasks.


                                  Examples

36    Examples of subprogram declarations:

37    procedure Traverse_Tree;
      procedure Increment(X : in out Integer);
      procedure Right_Indent(Margin : out Line_Size);          --  see 3.5.4
      procedure Switch(From, To : in out Link);                --  see 3.10.1

38    function Random return Probability;                      --  see 3.5.7

39    function Min_Cell(X : Link) return Cell;                 --  see 3.10.1
      function Next_Frame(K : Positive) return Frame;          --  see 3.10
      function Dot_Product(Left, Right : Vector) return Real;  --  see 3.6

40    function "*"(Left, Right : Matrix) return Matrix;        --  see 3.6

41    Examples of in parameters with default expressions:

42    procedure Print_Header(Pages  : in Natural;
                  Header : in Line    :=  (1 .. Line'Last => ' ');  --  see 3.6
                  Center : in Boolean := True);


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

5     a tagged type;

6     a task or protected type;

7     a nonprivate type with the reserved word limited in its declaration;

8     a composite type with a subcomponent of a by-reference type;

9     a private type whose full type is a by-reference type.

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

11    For parameters of other types, it is unspecified whether the parameter
is passed by copy or by reference.


                          Bounded (Run-Time) Errors

12    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

13    5  A formal parameter of mode in is a constant view (see 3.3); it cannot
      be updated within the subprogram_body.


6.3 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];

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


                               Legality Rules

4     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

5     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

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

7     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

8     Example of procedure body:

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

10    Example of a function body:

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


6.3.1 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/1   As explained in B.1, ``Interfacing Pragmas'', a convention can be
specified for an entity. Unless this International Standard states otherwise,
the default convention of an entity is Ada. For a callable entity or
access-to-subprogram type, the convention is called the calling convention.
The following conventions are defined by the language:

3     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 B.1).

4     The Intrinsic calling convention represents subprograms that are ``
      built in'' to the compiler. The default calling convention is Intrinsic
      for the following:

    5     an enumeration literal;

    6     a "/=" operator declared implicitly due to the declaration of "="
          (see 6.6);

    7     any other implicitly declared subprogram unless it is a dispatching
          operation of a tagged type;

    8     an inherited subprogram of a generic formal tagged type with unknown
          discriminants;

    9     an attribute that is a subprogram;

    10    a subprogram declared immediately within a protected_body.

11    The Access attribute is not allowed for Intrinsic subprograms.

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

13    The default calling convention is entry for an entry.

13.1/1 If not specified above as Intrinsic, the calling convention for any
      inherited or overriding dispatching operation of a tagged type is that
      of the corresponding subprogram of the parent type. The default calling
      convention for a new dispatching operation of a tagged type is the
      convention of the type.

14    Of these four conventions, only Ada and Intrinsic are allowed as a
convention_identifier in a pragma Convention, Import, or Export.

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

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

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

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

19    Two expressions are fully conformant if, after replacing each use of an
operator with the equivalent function_call:

20    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

21    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

21.1/1 each attribute_designator in one must be the same as the corresponding
      attribute_designator in the other; and

22    each primary that is a literal in one has the same value as the
      corresponding literal in the other.

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

24    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

25    An implementation may declare an operator declared in a language-defined
library unit to be intrinsic.


6.3.2 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
      10.1.5), 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.


6.4 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

7     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

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

9     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 8.6).


                              Dynamic Semantics

10    For the execution of a subprogram call, the name or prefix of the call
is evaluated, and each parameter_association is evaluated (see 6.4.1). 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 6.4.1).

11    The exception Program_Error is raised at the point of a function_call if
the function completes normally without executing a return_statement.

12    A function_call denotes a constant, as defined in 6.5; the nominal
subtype of the constant is given by the result subtype of the function.


                                  Examples

13    Examples of procedure calls:

14    Traverse_Tree;                                               --  see 6.1
      Print_Header(128, Title, True);                              --  see 6.1

15    Switch(From => X, To => Next);                               --  see 6.1
      Print_Header(128, Header => Title, Center => True);          --  see 6.1
      Print_Header(Header => Title, Center => True, Pages => 128); --  see 6.1

16    Examples of function calls:

17    Dot_Product(U, V)   --  see 6.1 and 6.3
      Clock               --  see 9.6
      F.all               --  presuming F is of an access-to-subprogram type - see 3.10

18    Examples of procedures with default expressions:

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

20    procedure Pair(Left, Right : in Person_Name := new Person);   --  see 3.10.1

21    Examples of their calls:

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

23    Pair;
      Pair(Left => new Person, Right => new Person);

      NOTES

24    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

25    Examples of overloaded subprograms:

26    procedure Put(X : in Integer);
      procedure Put(X : in String);

27    procedure Set(Tint   : in Color);
      procedure Set(Signal : in Light);

28    Examples of their calls:

29    Put(28);
      Put("no possible ambiguity here");

30    Set(Tint   => Red);
      Set(Signal => Red);
      Set(Color'(Red));

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


6.4.1 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 4.6) to its anonymous access type.


                              Dynamic Semantics

7     For the evaluation of a parameter_association:

8     The actual parameter is first evaluated.

9     For an access parameter, the access_definition is elaborated, which
      creates the anonymous access type.

10    For a parameter (of any mode) that is passed by reference (see 6.2), a
      view conversion of the actual parameter to the nominal subtype of the
      formal parameter is evaluated, and the formal parameter denotes that
      conversion.

11    For an in or in out parameter that is passed by copy (see 6.2), 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.

12    For an out parameter that is passed by copy, the formal parameter object
      is created, and:

        13    For an access type, the formal parameter is initialized from the
              value of the actual, without a constraint check;

        14    For a composite type with discriminants or that has implicit
              initial values for any subcomponents (see 3.3.1), the behavior
              is as for an in out parameter passed by copy.

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

16    A formal parameter of mode in out or out with discriminants is
constrained if either its nominal subtype or the actual parameter is
constrained.

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


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

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

10    If it is nonlimited, then the tag of the result is that of the result
      type.

11    A type is a return-by-reference type if it is a descendant of one of the
following:

12    a tagged limited type;

13    a task or protected type;

14    a nonprivate type with the reserved word limited in its declaration;

15    a composite type with a subcomponent of a return-by-reference type;

16    a private type whose full type is a return-by-reference type.

17    If the result type is a return-by-reference type, then a check is made
that the return expression is one of the following:

18    a name that denotes an object view whose accessibility level is not
      deeper than that of the master that elaborated the function body; or

19    a parenthesized expression or qualified_expression whose operand is one
      of these kinds of expressions.

20    The exception Program_Error is raised if this check fails.

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

22    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

23    Examples of return statements:

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


6.6 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);

