Return Statements

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

Syntax

Name Resolution Rules

{return expression} The expression, if any, of a return_statement is called the return expression. {result subtype (of a function)} 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. {expected type (return expression) [partial]} The expected type for a return expression is the result type of the corresponding function.

To be honest: The same applies to generic functions.

Legality Rules

{apply (to a callable construct by a return_statement)} 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.

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.

Reason: The requirement that a function body has to have at least one return_statement is a ``helpful'' restriction. There was been some interest in lifting this restriction, or allowing a raise statement to substitute for the return_statement. However, there was enough interest in leaving it as is that we decided not to change it.

Dynamic Semantics

{execution (return_statement) [partial]} For the execution of a return_statement, the expression (if any) is first evaluated and converted to the result subtype. {implicit subtype conversion (function return) [partial]}

Ramification: The conversion might raise Constraint_Error -- (see 4.6).

If the result type is class-wide, then the tag of the result is the tag of the value of the expression.

Ramification: This is true even if the tag of the return expression is different.

Reason: These rules ensure that a function whose result type is a specific tagged type always returns an object whose tag is that of the result type. This is important for dispatching on controlling result, and, if nonlimited, allows the caller to allocate the appropriate amount of space to hold the value being returned (assuming there are no discriminants).

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

Ramification: The above rules are such that there are no "Ada 83" types other than those containing tasks that are return-by-reference. This helps to minimize upward incompatibilities relating to return-by-reference.

{Accessibility_Check [partial]} {check, language-defined (Accessibility_Check)} If the result type is a return-by-reference type, then a check is made that the return expression is one of the following:

{Program_Error (raised by failure of run-time check)} The exception Program_Error is raised if this check fails.

Discussion: Compare the definition of return-by-reference with that of by-reference.

The return-by-reference types are all limited types except those that are limited only because of a limited private type with a nonlimited untagged full type.

Reason: {generic contract issue [partial]}

This check can often be performed at compile time. It is defined to be a run-time check to avoid generic contract model problems. In a future version of the standard, we anticipate that function return of a local variable will be illegal for all limited types, eliminating the need for the run-time check except for dereferences of an access parameter.

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. {assignment operation (during execution of a return_statement)} 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.

Ramification: The assignment operation does the necessary value adjustment, as described in 7.6, ``User-Defined Assignment and Finalization''. 7.6.1 describes when the anonymous constant is finalized.

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

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

Incompatibilities With Ada 83

{incompatibilities with Ada 83} In Ada 95, if the result type of a function has a part that is a task, then an attempt to return a local variable will raise Program_Error. In Ada 83, if a function returns a local variable containing a task, execution is erroneous according to AI83-00867. However, there are other situations where functions that return tasks (or that return a variant record only one of whose variants includes a task) are correct in Ada 83 but will raise Program_Error according to the new rules.

The rule change was made because there will be more types (protected types, limited controlled types) in Ada 95 for which it will be meaningless to return a local variable, and making all of these erroneous is unacceptable. The current rule was felt to be the simplest that kept upward incompatibilities to situations involving returning tasks, which are quite rare.

Wording Changes from Ada 83

This clause has been moved here from chapter 5, since it has mainly to do with subprograms.

A function now creates an anonymous object. This is necessary so that controlled types will work.

We have clarified that a return_statement applies to a callable construct, not to a callable entity.

There is no need to mention generics in the rules about where a return_statement can appear and what it applies to; the phrase ``body of a subprogram or generic subprogram'' is syntactic, and refers exactly to ``subprogram_body''.