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