Intrinsic Procedures
********************

This portion of the document is incomplete and undergoing massive expansion and editing.  All contributions and corrections are strongly encouraged.

Introduction to intrinsic procedures
====================================

Gfortran provides a rich set of intrinsic procedures that includes all the intrinsic procedures required by the Fortran 95 standard, a set of intrinsic procedures for backwards compatibility with Gnu Fortran 77 (i.e., g77), and a small selection of intrinsic procedures from the Fortran 2003 standard.  Any description here, which conflicts with a description in either the Fortran 95 standard or the Fortran 2003 standard, is unintentional and the standard(s) should be considered authoritative.

The enumeration of the KIND type parameter is processor defined in the Fortran 95 standard.  Gfortran defines the default integer type and default real type by INTEGER(KIND=4) and REAL(KIND=4), respectively.  The standard mandates that both data types shall have another kind, which have more precision.  On typical target architectures supports by gfortran, this kind type parameter is KIND=8. Hence, REAL(KIND=8) and DOUBLE PRECISION are equivalent. In the description of generic intrinsic procedures, the kind type parameter will be specified by KIND=*, and in the description of specific names for an intrinsic procedure the kind type parameter will be explicitly given (e.g., REAL(KIND=4) or REAL(KIND=8)).  Finally, for brevity the optional KIND= syntax will be omitted.

Many of the intrinsics procedures take one or more optional arguments. This document follows the convention used in the Fortran 95 standard, and denotes such arguments by square brackets.

Gfortran offers the -std=f95 and -std=gnu options, which can be used to restrict the set of intrinsic procedures to a given standard.  By default, gfortran sets the -std=gnu option, and so all intrinsic procedures describe here are accepted.  There is one caveat.  For a select group of intrinsic procedures, g77 implemented both a function and a subroutine.  Both classes have been implemented in gfortran for backwards compatibility with g77.  It is noted here that these functions and subroutines cannot be intermixed in a given subprogram.  In the descriptions that follow, the applicable option(s) is noted.

ABORT --- Abort the program
===========================

Description:
     ABORT causes immediate termination of the program.  On operating systems that support a core dump, ABORT will produce a core dump, which is suitable for debugging purposes.

Option:
     gnu

Type:
     non-elemental subroutine

Syntax:
     CALL ABORT

Return value:
     Does not return.

Example:

          program test_abort
            integer :: i = 1, j = 2
            if (i /= j) call abort
          end program test_abort

ABS --- Absolute value
======================

Description:
     ABS(X) computes the absolute value of X.

Option:
     f95, gnu

Type:
     elemental function

Syntax:
     X = ABS(X)

Arguments:

     X   The type of the argument shall be an INTEGER(*),
     REAL(*), or COMPLEX(*).

Return value:
     The return value is of the same type and kind as the argument except the return value is REAL(*) for a COMPLEX(*) argument.

Example:

          program test_abort
            integer :: i = -1
            real :: x = -1.e0
            complex :: z = (-1.e0,0.e0)
            i = abs(i)
            x = abs(x)
            x = abs(z)
          end program test_abort

Specific names:

     Name              Argument              Return type         Option
     CABS(Z)    COMPLEX(4) Z   REAL(4)      f95, gnu
     DABS(X)    REAL(8) X      REAL(8)      f95, gnu
     IABS(I)    INTEGER(4) I   INTEGER(4)   f95, gnu
     ZABS(Z)    COMPLEX(8) Z   COMPLEX(8)   gnu
     CDABS(Z)   COMPLEX(8) Z   COMPLEX(8)   gnu

ACHAR --- Character in ASCII collating sequence
===============================================

Description:
     ACHAR(I) returns the character located at position I in the ASCII collating sequence.

Option:
     f95, gnu

Type:
     elemental function

Syntax:
     C = ACHAR(I)

Arguments:

     I   The type shall be an INTEGER(*).

Return value:
     The return value is of type CHARACTER with a length of one.  The kind type parameter is the same as  KIND('A').

Example:

          program test_achar
            character c
            c = achar(32)
          end program test_abort

ACOS --- Arccosine function
===========================

Description:
     ACOS(X) computes the arccosine of its X.

Option:
     f95, gnu

Type:
     elemental function

Syntax:
     X = ACOS(X)

Arguments:

     X   The type shall be an REAL(*).

Return value:
     The return value is of type REAL(*) and it lies in the range  0 \leq \arccos (x) \leq \pi.

Example:

          program test_acos
            real(8) :: x = 0.866_8
            x = achar(x)
          end program test_acos

Specific names:

     Name              Argument            Return type         Option
     DACOS(X)   REAL(8) X    REAL(8)      f95, gnu

ADJUSTL --- Left adjust a string
================================

Description:
     ADJUSTL(STR) will left adjust a string by removing leading spaces. Spaces are inserted at the end of the string as needed.

Option:
     f95, gnu

Type:
     elemental function

Syntax:
     STR = ADJUSTL(STR)

Arguments:

     STR   The type shall be CHARACTER.

Return value:
     The return value is of type CHARACTER where leading spaces are removed and the same number of spaces are inserted on the end of STR.

Example:

          program test_adjustl
            character(len=20) :: str = '   gfortran'
            str = adjustl(str)
            print *, str
          end program test_adjustl

ADJUSTR --- Right adjust a string
=================================

Description:
     ADJUSTR(STR) will right adjust a string by removing trailing spaces. Spaces are inserted at the start of the string as needed.

Option:
     f95, gnu

Type:
     elemental function

Syntax:
     STR = ADJUSTR(STR)

Arguments:

     STR   The type shall be CHARACTER.

Return value:
     The return value is of type CHARACTER where trailing spaces are removed and the same number of spaces are inserted at the start of STR.

Example:

          program test_adjustr
            character(len=20) :: str = 'gfortran'
            str = adjustr(str)
            print *, str
          end program test_adjustr

AIMAG --- Imaginary part of complex number
==========================================

Description:
     AIMAG(Z) yields the imaginary part of complex argument Z.

Option:
     f95, gnu

Type:
     elemental function

Syntax:
     X = AIMAG(Z)

Arguments:

     Z   The type of the argument shall be COMPLEX(*).

Return value:
     The return value is of type real with the kind type parameter of the argument.

Example:

          program test_aimag
            complex(4) z4
            complex(8) z8
            z4 = cmplx(1.e0_4, 0.e0_4)
            z8 = cmplx(0.e0_8, 1.e0_8)
            print *, aimag(z4), dimag(z8)
          end program test_aimag

Specific names:

     Name              Argument              Return type         Option
     DIMAG(Z)   COMPLEX(8) Z   REAL(8)      f95, gnu

AINT --- Imaginary part of complex number
=========================================

Description:
     AINT(X [, KIND]) truncates its argument to a whole number.

Option:
     f95, gnu

Type:
     elemental function

Syntax:
     X = AINT(X)

     X = AINT(X, KIND)

Arguments:

     X      The type of the argument shall be REAL(*).
     KIND   (Optional) KIND shall be a scalar integer
     initialization expression.

Return value:
     The return value is of type real with the kind type parameter of the argument if the optional KIND is absence; otherwise, the kind type parameter will be given by KIND.  If the magnitude of X is less than one, then AINT(X) returns zero.  If the magnitude is equal to or greater than one, then it returns the largest whole number that does not exceed its magnitude.  The sign is the same as the sign of X.

Example:

          program test_aint
            real(4) x4
            real(8) x8
            x4 = 1.234E0_4
            x8 = 4.321_8
            print *, aint(x4), dint(x8)
            x8 = aint(x4,8)
          end program test_aint

Specific names:

     Name             Argument           Return type        Option
     DINT(X)   REAL(8) X   REAL(8)     f95, gnu

ALL --- All values in MASK along DIM are true
=============================================

Description:
     ALL(MASK [, DIM]) determines if all the values are true in MASK in the array along dimension DIM.

Option:
     f95, gnu

Type:
     transformational function

Syntax:
     L = ALL(MASK)

     L = ALL(MASK, DIM)

Arguments:

     MASK   The type of the argument shall be LOGICAL(*) and
     it shall not be scalar.
     DIM    (Optional) DIM shall be a scalar integer
     with a value that lies between one and the rank of MASK.

Return value:
     ALL(MASK) returns a scalar value of type LOGICAL(*) where the kind type parameter is the same as the kind type parameter of MASK.  If DIM is present, then ALL(MASK, DIM) returns an array with the rank of MASK minus 1.  The shape is determined from the shape of MASK where the DIM dimension is elided.

     (A)
          ALL(MASK) is true if all elements of MASK are true. It also is true if MASK has zero size; otherwise, it is false.

     (B)
          If the rank of MASK is one, then ALL(MASK,DIM) is equivalent to ALL(MASK).  If the rank is greater than one, then ALL(MASK,DIM) is determined by applying ALL to the array sections.

Example:

          program test_all
            logical l
            l = all((/.true., .true., .true./))
            print *, l
            call section
            contains
              subroutine section
                integer a(2,3), b(2,3)
                a = 1
                b = 1
                b(2,2) = 2
                print *, all(a .eq. b, 1)
                print *, all(a .eq. b, 2)
              end subroutine section
          end program test_all