Dummy Argument Properties

The INTENT, VALUE, and OPTIONAL attributes specify properties particular to dum-my arguments.

150 Chapter 5

5.9.1 The INTENT Attribute

The INTENT attribute specifies the intended use of a dummy argument. If specified, it can help detect errors, provide information for readers of the program, and give the compiler information that can be used to make the code more efficient.

Some dummy arguments only provide input data for a subprogram; some are only for output from the subprogram; others may be used for both input and output. IN-TENT has three explicit forms: IN, OUT, and INOUT which correspond respectively to the above three situations. A fourth case, where INTENT is not explicitly specified, is a bit more complicated.

If the intent of an argument is IN, the argument must not be modified during the execution of the subprogram. For a pointer dummy argument, it is the argumentʹs pointer association that must not be modified; for a nonpointer dummy argument, it is the argumentʹs value. These restrictions on INTENT (IN) arguments apply broadly, having implications both at compile time and at run time. The run-time implication is that the modification is prohibited even if it happens in some other lower-level proce-dure; this is not in general detectable at compile time. The compile-time implication is that an INTENT (IN) dummy argument must not appear in the subprogram in a con-text that would cause the argument to be modified; this applies regardless of whether or not the statement that it appears in would actually get executed for any particular invocation. For nonpointers, the forbidden contexts are called variable definition con-texts and are described in 16.3.1. For pointers, the forbidden concon-texts are:

1. A pointer object in a nullify statement.

2. The left-hand side of a pointer assignment statement.

3. An allocate object in an allocate or deallocate statement.

4. An actual argument corresponding to an INTENT (OUT) or INTENT (INOUT) pointer dummy argument.

If the intent of an argument is OUT, the argument becomes undefined on invoca-tion of the procedure. If the argument is a pointer, its associainvoca-tion status becomes unde-fined. If the argument is a nonpointer and is of a type that has default initialization, the default initialization is applied. The actual argument associated with an INTENT (OUT) dummy must be definable.

For an INTENT (OUT) dummy, any previous value of the actual argument is irrel-evant. If there is any situation in which you want to leave the previous value of the ac-tual argument unchanged or reference that value in any way, then INTENT (OUT) is the wrong choice. Even if no executable statement in the subroutine refers to the dum-my argument, the actual argument does not retain its previous value; the actual argu-ment will become undefined except for components that get default initialization.

Being undefined means that any program that references the value is nonstandard. Ac-tual implementations might realistically leave the value unchanged, change it to ran-dom garbage, or detect an error.

If the intent is INOUT, the argument may be used to communicate information to the subprogram and return information. As with INTENT (OUT), the corresponding

Declarations 151 actual argument is required to be definable. The difference between INTENT (OUT) and INTENT (INOUT) is that an INTENT (INOUT) dummy acquires its starting defini-tion status and value from that of the actual argument; it does not become undefined or have default initialization applied.

An unspecified intent is similar to INTENT (INOUT), with just one subtle distinc-tion. For INTENT (INOUT), the actual argument is required to be definable. For un-specified intent, the actual argument is required to be definable if execution of the procedure causes definition or undefinition of the dummy. This is a run-time require-ment that applies independently to each invocation of the procedure. There can be some invocations that trigger the requirement and other invocations of the same proce-dure that do not. The following illustrates a trivial case of this:

program illustrate_unspecified real :: x

call maybe_set(.false., 4.567) call maybe_set(.true., x) end program

subroutine maybe_set (set, x) logical, intent(in) :: set real :: x

if (set) x = 1.23 print *, x

end subroutine

This is valid because the first call to the subroutine does not cause definition or un-definition of the dummy x. The second call does cause such un-definition, but the actual argument for that call is definable, so it is ok. Using unspecified intent makes it diffi-cult for the compiler to diagnose some kinds of problems; it is usually recommended to specify intent explicitly in new code and to regard unspecified intent as primarily a compatibility feature for old codes.

The INTENT attribute can be specified in a type declaration statement or in a IN-TENT statement. The form of a ININ-TENT statement (R536) is:

INTENT ( intent-spec ) [ :: ] dummy-argument-name-list where an intent specification is IN, OUT, or INOUT.

Rules and restrictions:

1. The INTENT attribute may be specified only for a dummy argument.

2. An intent must not be specified for a procedure unless it is a procedure pointer.

This is because the concepts of definition and modification do not apply to proce-dures other than procedure pointers.

The following are examples of INTENT specifications:

152 Chapter 5

• entity-oriented

SUBROUTINE MOVE (FROM, TO) USE PERSON_MODULE

TYPE (PERSON), INTENT (IN) :: FROM TYPE (PERSON), INTENT (OUT) :: TO

. . .

SUBROUTINE SUB (X, Y)

INTEGER, INTENT (INOUT) :: X, Y . . .

• attribute-oriented

SUBROUTINE MOVE (FROM, TO) USE PERSON_MODULE TYPE (PERSON) FROM, TO INTENT (IN) FROM INTENT (OUT) TO

. . .

SUBROUTINE SUB (X, Y) INTEGER X, Y

INTENT (INOUT) X, Y . . .

5.9.2 The VALUE Attribute

The VALUE attribute specifies a form of argument association for a dummy argument.

The dummy argument is not associated with the actual argument itself, but rather with an anonymous temporary variable. The initial value of this temporary variable is taken from the value of the actual argument. The dummy argumentʹs value may be modified during execution of the procedure (unless the dummy also has the INTENT (IN) at-tribute), but such modifications affect only the temporary variable—not the actual ar-gument.

Although C interoperability was a major motivation for the VALUE attribute, it has utility independent of C in situations where there is a need to modify the dummy ar-gumentʹs value without having such modifications change the actual arar-gumentʹs value, or even where it would not be allowed to change the actual argumentʹs value. Without the VALUE attribute, such situations would require that the programmer explicitly copy the dummy argument to a temporary variable. The VALUE attribute makes such a copy automatic and transparent.

The VALUE attribute can be specified in a type declaration statement or in a VAL-UE statement. The form of a VALVAL-UE statement (R547) is:

VALUE [ :: ] dummy-argument-name-list Rules and restrictions:

1. The VALUE attribute may be specified only for a dummy data argument.

Declarations 153 2. For a variable with the VALUE attribute, any length type parameter values must ei-ther be specified by initialization expressions or be omitted (in which case they would take their default values).

The following are examples of VALUE specifications:

• entity-oriented

subroutine sub(x) real, value :: x . . .

• attribute-oriented subroutine sub(x) real :: x value :: x . . .

5.9.3 The OPTIONAL Attribute

The OPTIONAL attribute for a dummy argument specifies that a procedure reference may omit the corresponding actual argument. The PRESENT intrinsic function can be used to test whether the actual argument was or was not present in a particular invoca-tion of the procedure.

The syntax for referencing a procedure with omitted optional arguments is pre-sented in 12.6.2.

The OPTIONAL attribute can be specified in a type declaration statement or in an OPTIONAL statement. The form of an OPTIONAL statement (R537) is:

OPTIONAL [ ^:: ] dummy-argument-name-list Rules and restrictions:

1. The OPTIONAL attribute may be specified only for dummy arguments.

The following are examples of OPTIONAL specifications:

• entity-oriented

INTEGER, INTENT (IN), OPTIONAL :: SIZEX LOGICAL, INTENT (IN), OPTIONAL :: FAST

• attribute-oriented

OPTIONAL SIZEX, FAST

Argument optionality is useful in several situations. An argument might be irrele-vant to some invocations of a procedure. A procedure might have several output argu-ments, some of which are not needed from a particular invocation. Although there is no direct mechanism for specifying a default value for an omitted argument, the effect

154 Chapter 5 of a default value can be achieved by using a local variable in the procedure, as in the following example.

subroutine do_something(...other arguments..., tolerance) real, optional, intent(in) :: tolerance

. . .

real :: tolerance_local . . .

if (present(tolerance)) then tolerance_local = tolerance else

tolerance_local = 0.001 end if

. . .

Such default values allow a procedure to accommodate common simple situations with simple references to the procedure, while still allowing detailed specification when needed.

The presence of an optional argument can also be used like a logical input variable to select an option in the code. This is most natural when applied to an argument that has data needed for one option, but irrelevant to the other as illustrated in the follow-ing example:

subroutine minimize(tolerance)

real, optional, intent(in) :: tolerance if (present(tolerance)) then

call full_method(tolerance) else

call simple_method end if

. . .

If an optional argument is not present for a particular invocation of a procedure, that argument is subject to the restrictions detailed in 12.6.2.