A function subprogram is invoked in an expression and returns a single value (a function result) that is used to evaluate the expression.
The FUNCTION statement is the initial statement of a function subprogram. It takes the following form:
[prefix] FUNCTION name ([d-arg-list]) [RESULT (r-name)]
type [keyword] keyword [type]
Keyword | Meaning |
---|---|
RECURSIVE | Permits direct recursion to occur. If a function is directly recursive and array valued, RESULT must also be specified (see Section 8.4.1.1). |
PURE | Asserts that the procedure has no side effects (see Section 8.4.1.2). |
ELEMENTAL | Restricted form of pure procedure that acts on one array element at a time (see Section 8.4.1.3). |
EXTRINSIC(HPF)[1] | Causes the procedure to execute in the single-threaded model known as "global HPF" -- essentially the standard Fortran model, but with some extensions and a few restrictions to allow for better parallelization. This is the default if no extrinsic prefix is specified (either explicitly or implicitly in the declaration of a host module or subprogram). |
EXTRINSIC(HPF_LOCAL)[1] | Causes multiple independent copies of the same procedure to execute on different data on multiple processors. |
EXTRINSIC(HPF_SERIAL)[1] | Causes the procedure to execute as if it were a single process executing on a scalar computer system. |
[1] This keyword is allowed on all platforms, but is functional only in parallel programs on Tru64 UNIX systems. For more information on EXTRINSIC keywords, see the Compaq High Performance Fortran 90 HPF and PSE Manual. |
The function name can be followed by the length of the data type. The length is specified by an asterisk (*) followed by any unsigned, nonzero integer that is a valid length for the function's type. For example, REAL FUNCTION LGFUNC*8 (Y, Z) specifies the function result as REAL(8) (or REAL*8).
This optional length specification is not permitted if the length has already been specified following the keyword CHARACTER.
The type and kind parameters (if any) of the function's result can be defined in the FUNCTION statement or in a type declaration statement within the function subprogram, but not both. If no type is specified, the type is determined by implicit typing rules in effect for the function subprogram.
Execution begins with the first executable construct or statement following the FUNCTION statement. Control returns to the calling program unit once the END statement (or a RETURN statement) is executed.
If you specify CHARACTER*(*), the function assumes the length declared for it in the program unit that invokes it. This type of character function can have different lengths when it is invoked by different program units. If the length is specified as an integer constant, the value must agree with the length of the function specified in the program unit that invokes the function. If no length is specified, a length of 1 is assumed.
If the function is array-valued or a pointer, the declarations within the function must state these attributes for the function result name. The specification of the function result attributes, dummy argument attributes, and the information in the procedure heading collectively define the interface of the function.
The value of the result variable is returned by the function when it completes execution. Certain rules apply depending on whether the result is a pointer, as follows:
The shape of the value returned by the function is determined by the shape of the result variable when the function completes execution.
A function subprogram cannot contain a SUBROUTINE statement, a BLOCK DATA statement, a PROGRAM statement, or another FUNCTION statement. ENTRY statements can be included to provide multiple entry points to the subprogram.
Section 8.4.2.1 describes the RESULT keyword and Section 8.4.2.2 describes function references.
The following example uses the Newton-Raphson iteration method
(F(X) = cosh(X) + cos(X) - A = 0)
to get the root of the
function:
FUNCTION ROOT(A) X = 1.0 DO EX = EXP(X) EMINX = 1./EX ROOT = X - ((EX+EMINX)*.5+COS(X)-A)/((EX-EMINX)*.5-SIN(X)) IF (ABS((X-ROOT)/ROOT) .LT. 1E-6) RETURN X = ROOT END DO END
In the preceding example, the following formula is calculated repeatedly until the difference between Xi and Xi+1 is less than 1.0E-6:
-cosh(Xi) + cos(Xi) - A Xi+1 = Xi ------------------------- sinh(Xi) - sin(Xi)
The following example shows an assumed-length character function:
CHARACTER*(*) FUNCTION REDO(CARG) CHARACTER*1 CARG DO I=1,LEN(REDO) REDO(I:I) = CARG END DO RETURN END FUNCTION
This function returns the value of its argument, repeated to fill the length of the function.
Within any given program unit, all references to an assumed-length character function must have the same length. In the following example, the REDO function has a length of 1000:
CHARACTER*1000 REDO, MANYAS, MANYZS MANYAS = REDO('A') MANYZS = REDO('Z')
Another program unit within the executable program can specify a different length. For example, the following REDO function has a length of 2:
CHARACTER HOLD*6, REDO*2 HOLD = REDO('A')//REDO('B')//REDO('C')
The following example shows a dynamic array-valued function:
FUNCTION SUB (N) REAL, DIMENSION(N) :: SUB ... END FUNCTION