Fortran Procedures - Subroutines

In a previous Kumite, I mentioned that there are two types of procedures in Fortran:

1. Functions - These evaluate to a given value which is returned to the caller (for further computation by other parts of the program, for example)
2. Subroutines - These only perform a set of actions and do not evaluate to any value

This Kumite aims to demonstrate how to define and invoke a Fortran subroutine.

A Fortran subroutine is in fact declared/defined in the same way as a function except the function keyword (in both the first and last lines) are replaced with subroutine. Pretty much everything else that holds for functions also holds for subroutines, with the exception of a lack of return value (and therefore result(<res_var>) annotation is not permitted). You can even declare a subroutine as recursive (and/or even pure)!

module Solution
  implicit none
contains
  recursive subroutine print1ToN(n)
    integer :: n
    if (n > 0) then
      call print1ToN(n - 1) ! NOTE: See explanation below code example
      print "(I0)", n
    end if
  end subroutine print1ToN
end module Solution

When invoking a subroutine, the syntax is slightly different - you have to add the call keyword in front of the subroutine name, like such:

program TestCases
  use Solution
  implicit none
  call print1ToN(10)
  ! > 1
  ! > 2
  ! > ... (you get the idea ;) )
  ! > 10
end program TestCases

Interfacing

In Fortran modules, it is possible to "overload" a prodecure with several variants, each accepting different types/numbers of arguments through interfacing. An interface is essentially a named alias to one or more defined procedures. For example, when we first introduced functions, our add function was only capable of accepting two default (32-bit) integers and compute its sum (as a 32-bit integer). What if we wanted our add function to work on reals as well? Or complex numbers? In that case, all we have to do is to define three separate functions and implement them accordingly - let's call them addIntegers, addReals and addComplexNumbers. After that, we alias them all under the same name add through interfacing which is achieved by using the interface keyword and has the following syntax (ALL_CAPS denote placeholders):

interface ALIAS_NAME
  module procedure PROC_1, PROC_2, ..., PROC_N
end interface ALIAS_NAME

The interface is always placed at the top section of the module, i.e. before the contains keyword:

module InterfacingExample
  implicit none
  ! Our interface
  interface add
    ! The `addIntegers`, `addReals` and `addComplexNumbers`
    ! functions should all be aliased number the name `add`
    module procedure addIntegers, addReals, addComplexNumbers
  end interface add
contains
  pure function addIntegers(a, b) result(c)
    integer, intent(in) :: a, b
    integer :: c
    c = a + b
  end function addIntegers
  pure function addReals(a, b) result(c)
    real, intent(in) :: a, b
    real :: c
    c = a + b
  end function addReals
  pure function addComplexNumbers(a, b) result(c)
    complex, intent(in) :: a, b
    complex :: c
    c = a + b
  end function addComplexNumbers
end module InterfacingExample

Now let's test it in our program:

program Main
  use InterfacingExample
  implicit none
  print *, add(1, 2) ! > 3 (perhaps with padding)
  print *, add(3.5, 4.5) ! > 8.0 (perhaps with padding)
  print *, add(cmplx(3, -4), cmplx(2, 1)) ! > (5.0, -3.0) (perhaps with padding)
end program Main

Our alias works as expected. However, at this point, you might be wondering if the functions are still accessible through their original names (e.g. addIntegers). If that is the case then your doubts are well-founded - the functions are still accessible through their original names (which may not be desirable). To hide the original names of the functions and expose only the alias, simply declare the original function names as private the same way you would variables/constants:

module InterfacingExample
  implicit none
  private :: addIntegers, addReals, addComplexNumbers
  ! Our interface
  interface add
    ! The `addIntegers`, `addReals` and `addComplexNumbers`
    ! functions should all be aliased number the name `add`
    module procedure addIntegers, addReals, addComplexNumbers
  end interface add
contains
  pure function addIntegers(a, b) result(c)
    integer, intent(in) :: a, b
    integer :: c
    c = a + b
  end function addIntegers
  pure function addReals(a, b) result(c)
    real, intent(in) :: a, b
    real :: c
    c = a + b
  end function addReals
  pure function addComplexNumbers(a, b) result(c)
    complex, intent(in) :: a, b
    complex :: c
    c = a + b
  end function addComplexNumbers
end module InterfacingExample

Just a simple C function void say_hello() written in NASM v2.11.x which prints Hello World! to the console.

Operator Overloading

In Fortran, operator overloading is done via interfacing. The syntax is almost identical to overloading procedures except the name of the alias is replaced by operator (OPERATOR) (where OPERATOR is a placeholder for the actual operator).

Unlike some programming languages such as Haskell, operators to be overloaded cannot contain arbitrary symbols (or a sequence thereof). Only the following operators and types of operators can be overloaded/defined:

• Symbol / symbol combinations already defined as operators in Fortran (e.g. +, -, *, /, ==, /=, etc.)
• .OPERATOR_NAME. where OPERATOR_NAME may only contain English letters (not even numbers, not even underscore)

Operators can be unary or binary or both (of the form OPERATOR OPERAND or OPERAND_1 OPERATOR OPERAND_2) depending on whether the function(s) implementing it accept one or two arguments. However, for operators intrinsic to Fortran (such as * or /), the functions implemeting their overloads may only accept as many arguments as they were originally defined (e.g. you cannot overload * to accept only one operand).

Note that operators must be pure in Fortran, i.e. they are not permitted to mutate their operands. Therefore, functions implementing the overloaded operator must be declared pure (or if not, at least all input parameters must be declared intent(in)).

Pointers

Fortran has basic support for pointers. A pointer is a rather primitive type of reference - it is essentially a memory address (associated with a given type) which is said to "point to" the data it is referencing. Unlike C/C++/ObjC, Fortran does not support pointers to pointers, function pointers, arrays of pointers or pointer arithmetic but it is still sufficient to allow us to define simple recursive datatypes such as linked lists or binary trees.

To declare a pointer:

integer, pointer :: p ! `p` is a non-associated integer pointer

To associate a pointer to a target:

! The `target` annotation is required for a pointer to point to it
! Otherwise, `n` is just another ordinary integer
integer, target :: n = 42
integer, pointer :: p => n ! `p` is now associated with `n`

To dereference a pointer:

integer, target :: n = 42
integer, pointer :: p => n ! `p` points to `n`
p = 100 ! `p` is automatically dereferenced and its target `n` set to 100

To associate a pointer to another target:

integer, target :: m = 100, n = 42
integer, pointer :: p => n ! `p` points to `n`
p => m ! `p` now points to `m` instead

To make two (or more) pointers point to the same target:

integer, target :: n = 42
integer, pointer :: p1, p2
p1 => n ! `p1` points to `n`
p2 => p1 ! `p2` now points to the TARGET of `p1` which is `n`
! REMEMBER: `p2` does NOT point to `p1` - pointers
! to pointers are not permitted in Fortran

To define a null pointer (i.e. one that does not reference any data):

integer, pointer :: p => null()

To allocate memory for a pointer instead of pointing it to a pre-existing target:

integer, pointer :: p
allocate(p) ! Allocate memory under pointer (just sufficient for one integer)
! Do something with `p`.  Make sure `p` doesn't point to anything else
! before it is deallocated (otherwise a memory leak will occur)!
deallocate(p) ! Free the memory under the pointer

To check whether a pointer is associated with a target:

associated(p) ! Checks whether `p` is associated with a target
! Evaluates to the corresponding logical value
! (.true. if associated, .false. otherwise)

The main code example in this Kumite involves derived data types.

Return "Hello World."

Dynamic Memory Allocation by using C library malloc() function

It is possible to allocate memory dynamically in NASM (obviously, otherwise how would it be possible in C and other higher-level languages?) and the easiest way to do it is probably by relying on the C library function malloc().

This Kumite is created to test JQuery support on Codewars.