Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 39 ยท Procedures and Modules

Argument Intent, Optional and Keyword Arguments

Use intent(in), intent(out) and intent(inout), optional arguments with present(), and keyword calls to write safe, self-documenting Fortran procedures.

Because Fortran passes arguments by reference, a procedure could change anything it is given. The intent attribute states your plan: this argument is read only, this one is produced, this one is both. The compiler then holds you to it. Combined with optional arguments and keyword calls, it makes procedure signatures read almost like documentation.

This lesson assumes you know subroutines and functions.

The three intents

FORTRAN
subroutine accumulate(total, x, count)
  real,    intent(inout) :: total   ! read and updated
  real,    intent(in)    :: x       ! only read
  integer, intent(out)   :: count   ! only written
  total = total + x
  count = 1
end subroutine accumulate
Intent Meaning What the compiler enforces
intent(in) input only assigning to it is an error; the actual argument may be an expression or constant
intent(out) output only the value on entry is undefined; the actual argument must be a variable
intent(inout) input and output the actual argument must be a variable with a value already

Two rules deserve emphasis. First, an intent(out) dummy argument becomes undefined when the procedure starts (allocatable ones are deallocated, and derived types with default initialization are reset). Never read it before assigning. Second, put intent on every dummy argument. It costs nothing and catches real bugs such as x = x + 1 on an input.

Python Stand-in: what each intent promises

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Optional arguments

Mark a dummy argument optional and callers may leave it out. Inside the procedure you must test it with present() before use:

FORTRAN
subroutine report(value, label, unit)
  real, intent(in) :: value
  character(*), intent(in), optional :: label
  character(*), intent(in), optional :: unit

  if (present(label)) then
    write (*, "(a, ': ')", advance="no") label
  end if
  write (*, "(f8.3)", advance="no") value
  if (present(unit)) write (*, "(1x, a)", advance="no") unit
  write (*, *)
end subroutine report

character(*) takes its length from the actual argument. Reading an absent optional argument is undefined behavior, so always guard it. If you need to pass an optional through to another procedure, pass it on directly: an absent optional stays absent downstream.

Optional arguments (and everything in the next section) require an explicit interface, so the procedure must be in a module or internal. See modules and use.

Keyword arguments

At the call site you may name the dummy argument:

FORTRAN
call report(21.375)
call report(21.375, label="Temperature")
call report(21.375, unit="C", label="Temperature")

After the first keyword, every later argument must also be a keyword. Keywords make long argument lists readable and let you skip optional arguments without commas. Fortran's intrinsics use them too: sum(a, dim=2), maxval(a, mask=a > 0), reshape(src, shape=[3, 2], order=[2, 1]).

Python Stand-in: optional and keyword arguments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Default values for optional arguments

Fortran has no default-value syntax. The idiom is a local variable:

FORTRAN
function power(x, p) result(y)
  real, intent(in) :: x
  integer, intent(in), optional :: p
  real :: y
  integer :: pp
  pp = 2
  if (present(p)) pp = p
  y = x**pp
end function power

Here power(3.0) gives 9.0 and power(3.0, p=3) gives 27.0.

Intent and function purity

Function arguments should almost always be intent(in). A function that modifies its inputs makes expressions such as f(x) + f(x) order dependent, because Fortran does not fix the order in which operands are evaluated. The pure prefix (see recursion and pure procedures) turns this advice into a compiler rule: every dummy argument of a pure function must be intent(in) (or a procedure, or value).

The value attribute

value makes a dummy argument a private copy, passed by value, like C:

FORTRAN
subroutine bump(n)
  integer, value :: n
  n = n + 1        ! changes only the local copy
end subroutine bump

You rarely need it in ordinary Fortran, but it is required for C interoperability (see C interoperability). Do not combine value with intent(out) or intent(inout).

Common mistakes

  • Omitting intent. The code works until an accidental write corrupts the caller.
  • Reading an intent(out) argument before setting it.
  • Reading an optional argument without present().
  • Passing a constant such as 5.0 to an intent(inout) or intent(out) argument; the compiler rejects it, or worse, the program crashes at runtime in legacy code.
  • Mixing positional arguments after a keyword argument.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which intent should a dummy argument have if the procedure only reads it?

    intent(in) makes the argument read only, and it also allows constants and expressions as actual arguments.
  2. 2. What must you do before using an optional dummy argument?

    Using an absent optional argument is undefined. present(arg) tells you whether the caller supplied it.
  3. 3. What is true of the value of an intent(out) argument on entry?

    intent(out) means the procedure produces the value, so the incoming contents must not be relied on.
  4. 4. Which call is valid after report(value, label, unit)?

    Once you use a keyword, all later arguments must be keywords. Order does not matter among keyword arguments.

Summary

  • Give every dummy argument an intent: in, out or inout.
  • optional arguments need present() before use; emulate defaults with a local variable.
  • Keyword arguments make calls self-documenting and allow skipping optionals.
  • value passes a copy and is mainly for C interoperability.
  • Optional and keyword arguments need an explicit interface (a module or internal procedure).

Next: Modules and the use statement