diff options
Diffstat (limited to 'gcc-4.8.1/gcc/fortran/intrinsic.texi')
| -rw-r--r-- | gcc-4.8.1/gcc/fortran/intrinsic.texi | 13207 |
1 files changed, 0 insertions, 13207 deletions
diff --git a/gcc-4.8.1/gcc/fortran/intrinsic.texi b/gcc-4.8.1/gcc/fortran/intrinsic.texi deleted file mode 100644 index 390750186..000000000 --- a/gcc-4.8.1/gcc/fortran/intrinsic.texi +++ /dev/null @@ -1,13207 +0,0 @@ -@ignore -Copyright (C) 2005-2013 Free Software Foundation, Inc. -This is part of the GNU Fortran manual. -For copying conditions, see the file gfortran.texi. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``Funding Free Software'', the Front-Cover -Texts being (a) (see below), and with the Back-Cover Texts being (b) -(see below). A copy of the license is included in the gfdl(7) man page. - - -Some basic guidelines for editing this document: - - (1) The intrinsic procedures are to be listed in alphabetical order. - (2) The generic name is to be used. - (3) The specific names are included in the function index and in a - table at the end of the node (See ABS entry). - (4) Try to maintain the same style for each entry. - - -@end ignore - -@tex -\gdef\acos{\mathop{\rm acos}\nolimits} -\gdef\asin{\mathop{\rm asin}\nolimits} -\gdef\atan{\mathop{\rm atan}\nolimits} -\gdef\acosh{\mathop{\rm acosh}\nolimits} -\gdef\asinh{\mathop{\rm asinh}\nolimits} -\gdef\atanh{\mathop{\rm atanh}\nolimits} -@end tex - - -@node Intrinsic Procedures -@chapter Intrinsic Procedures -@cindex intrinsic procedures - -@menu -* Introduction: Introduction to Intrinsics -* @code{ABORT}: ABORT, Abort the program -* @code{ABS}: ABS, Absolute value -* @code{ACCESS}: ACCESS, Checks file access modes -* @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence -* @code{ACOS}: ACOS, Arccosine function -* @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function -* @code{ADJUSTL}: ADJUSTL, Left adjust a string -* @code{ADJUSTR}: ADJUSTR, Right adjust a string -* @code{AIMAG}: AIMAG, Imaginary part of complex number -* @code{AINT}: AINT, Truncate to a whole number -* @code{ALARM}: ALARM, Set an alarm clock -* @code{ALL}: ALL, Determine if all values are true -* @code{ALLOCATED}: ALLOCATED, Status of allocatable entity -* @code{AND}: AND, Bitwise logical AND -* @code{ANINT}: ANINT, Nearest whole number -* @code{ANY}: ANY, Determine if any values are true -* @code{ASIN}: ASIN, Arcsine function -* @code{ASINH}: ASINH, Inverse hyperbolic sine function -* @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair -* @code{ATAN}: ATAN, Arctangent function -* @code{ATAN2}: ATAN2, Arctangent function -* @code{ATANH}: ATANH, Inverse hyperbolic tangent function -* @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically -* @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically -* @code{BACKTRACE}: BACKTRACE, Show a backtrace -* @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0 -* @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1 -* @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind -* @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0 -* @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1 -* @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind -* @code{BGE}: BGE, Bitwise greater than or equal to -* @code{BGT}: BGT, Bitwise greater than -* @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function -* @code{BLE}: BLE, Bitwise less than or equal to -* @code{BLT}: BLT, Bitwise less than -* @code{BTEST}: BTEST, Bit test function -* @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer -* @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer -* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer -* @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure -* @code{C_LOC}: C_LOC, Obtain the C address of an object -* @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression -* @code{CEILING}: CEILING, Integer ceiling function -* @code{CHAR}: CHAR, Integer-to-character conversion function -* @code{CHDIR}: CHDIR, Change working directory -* @code{CHMOD}: CHMOD, Change access permissions of files -* @code{CMPLX}: CMPLX, Complex conversion function -* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments -* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler -* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string -* @code{COMPLEX}: COMPLEX, Complex conversion function -* @code{CONJG}: CONJG, Complex conjugate function -* @code{COS}: COS, Cosine function -* @code{COSH}: COSH, Hyperbolic cosine function -* @code{COUNT}: COUNT, Count occurrences of TRUE in an array -* @code{CPU_TIME}: CPU_TIME, CPU time subroutine -* @code{CSHIFT}: CSHIFT, Circular shift elements of an array -* @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string -* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine -* @code{DBLE}: DBLE, Double precision conversion function -* @code{DCMPLX}: DCMPLX, Double complex conversion function -* @code{DIGITS}: DIGITS, Significant digits function -* @code{DIM}: DIM, Positive difference -* @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function -* @code{DPROD}: DPROD, Double product function -* @code{DREAL}: DREAL, Double real part function -* @code{DSHIFTL}: DSHIFTL, Combined left shift -* @code{DSHIFTR}: DSHIFTR, Combined right shift -* @code{DTIME}: DTIME, Execution time subroutine (or function) -* @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array -* @code{EPSILON}: EPSILON, Epsilon function -* @code{ERF}: ERF, Error function -* @code{ERFC}: ERFC, Complementary error function -* @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function -* @code{ETIME}: ETIME, Execution time subroutine (or function) -* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command -* @code{EXIT}: EXIT, Exit the program with status. -* @code{EXP}: EXP, Exponential function -* @code{EXPONENT}: EXPONENT, Exponent function -* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension -* @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string -* @code{FGET}: FGET, Read a single character in stream mode from stdin -* @code{FGETC}: FGETC, Read a single character in stream mode -* @code{FLOOR}: FLOOR, Integer floor function -* @code{FLUSH}: FLUSH, Flush I/O unit(s) -* @code{FNUM}: FNUM, File number function -* @code{FPUT}: FPUT, Write a single character in stream mode to stdout -* @code{FPUTC}: FPUTC, Write a single character in stream mode -* @code{FRACTION}: FRACTION, Fractional part of the model representation -* @code{FREE}: FREE, Memory de-allocation subroutine -* @code{FSEEK}: FSEEK, Low level file positioning subroutine -* @code{FSTAT}: FSTAT, Get file status -* @code{FTELL}: FTELL, Current stream position -* @code{GAMMA}: GAMMA, Gamma function -* @code{GERROR}: GERROR, Get last system error message -* @code{GETARG}: GETARG, Get command line arguments -* @code{GET_COMMAND}: GET_COMMAND, Get the entire command line -* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments -* @code{GETCWD}: GETCWD, Get current working directory -* @code{GETENV}: GETENV, Get an environmental variable -* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable -* @code{GETGID}: GETGID, Group ID function -* @code{GETLOG}: GETLOG, Get login name -* @code{GETPID}: GETPID, Process ID function -* @code{GETUID}: GETUID, User ID function -* @code{GMTIME}: GMTIME, Convert time to GMT info -* @code{HOSTNM}: HOSTNM, Get system host name -* @code{HUGE}: HUGE, Largest number of a kind -* @code{HYPOT}: HYPOT, Euclidean distance function -* @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence -* @code{IALL}: IALL, Bitwise AND of array elements -* @code{IAND}: IAND, Bitwise logical and -* @code{IANY}: IANY, Bitwise OR of array elements -* @code{IARGC}: IARGC, Get the number of command line arguments -* @code{IBCLR}: IBCLR, Clear bit -* @code{IBITS}: IBITS, Bit extraction -* @code{IBSET}: IBSET, Set bit -* @code{ICHAR}: ICHAR, Character-to-integer conversion function -* @code{IDATE}: IDATE, Current local time (day/month/year) -* @code{IEOR}: IEOR, Bitwise logical exclusive or -* @code{IERRNO}: IERRNO, Function to get the last system error number -* @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion -* @code{INDEX}: INDEX intrinsic, Position of a substring within a string -* @code{INT}: INT, Convert to integer type -* @code{INT2}: INT2, Convert to 16-bit integer type -* @code{INT8}: INT8, Convert to 64-bit integer type -* @code{IOR}: IOR, Bitwise logical or -* @code{IPARITY}: IPARITY, Bitwise XOR of array elements -* @code{IRAND}: IRAND, Integer pseudo-random number -* @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value -* @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value -* @code{ISATTY}: ISATTY, Whether a unit is a terminal device -* @code{ISHFT}: ISHFT, Shift bits -* @code{ISHFTC}: ISHFTC, Shift bits circularly -* @code{ISNAN}: ISNAN, Tests for a NaN -* @code{ITIME}: ITIME, Current local time (hour/minutes/seconds) -* @code{KILL}: KILL, Send a signal to a process -* @code{KIND}: KIND, Kind of an entity -* @code{LBOUND}: LBOUND, Lower dimension bounds of an array -* @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array -* @code{LEADZ}: LEADZ, Number of leading zero bits of an integer -* @code{LEN}: LEN, Length of a character entity -* @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters -* @code{LGE}: LGE, Lexical greater than or equal -* @code{LGT}: LGT, Lexical greater than -* @code{LINK}: LINK, Create a hard link -* @code{LLE}: LLE, Lexical less than or equal -* @code{LLT}: LLT, Lexical less than -* @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string -* @code{LOC}: LOC, Returns the address of a variable -* @code{LOG}: LOG, Logarithm function -* @code{LOG10}: LOG10, Base 10 logarithm function -* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function -* @code{LOGICAL}: LOGICAL, Convert to logical type -* @code{LONG}: LONG, Convert to integer type -* @code{LSHIFT}: LSHIFT, Left shift bits -* @code{LSTAT}: LSTAT, Get file status -* @code{LTIME}: LTIME, Convert time to local time info -* @code{MALLOC}: MALLOC, Dynamic memory allocation function -* @code{MASKL}: MASKL, Left justified mask -* @code{MASKR}: MASKR, Right justified mask -* @code{MATMUL}: MATMUL, matrix multiplication -* @code{MAX}: MAX, Maximum value of an argument list -* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind -* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array -* @code{MAXVAL}: MAXVAL, Maximum value of an array -* @code{MCLOCK}: MCLOCK, Time function -* @code{MCLOCK8}: MCLOCK8, Time function (64-bit) -* @code{MERGE}: MERGE, Merge arrays -* @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask -* @code{MIN}: MIN, Minimum value of an argument list -* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind -* @code{MINLOC}: MINLOC, Location of the minimum value within an array -* @code{MINVAL}: MINVAL, Minimum value of an array -* @code{MOD}: MOD, Remainder function -* @code{MODULO}: MODULO, Modulo function -* @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another -* @code{MVBITS}: MVBITS, Move bits from one integer to another -* @code{NEAREST}: NEAREST, Nearest representable number -* @code{NEW_LINE}: NEW_LINE, New line character -* @code{NINT}: NINT, Nearest whole number -* @code{NORM2}: NORM2, Euclidean vector norm -* @code{NOT}: NOT, Logical negation -* @code{NULL}: NULL, Function that returns an disassociated pointer -* @code{NUM_IMAGES}: NUM_IMAGES, Number of images -* @code{OR}: OR, Bitwise logical OR -* @code{PACK}: PACK, Pack an array into an array of rank one -* @code{PARITY}: PARITY, Reduction with exclusive OR -* @code{PERROR}: PERROR, Print system error message -* @code{POPCNT}: POPCNT, Number of bits set -* @code{POPPAR}: POPPAR, Parity of the number of bits set -* @code{PRECISION}: PRECISION, Decimal precision of a real kind -* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified -* @code{PRODUCT}: PRODUCT, Product of array elements -* @code{RADIX}: RADIX, Base of a data model -* @code{RAN}: RAN, Real pseudo-random number -* @code{RAND}: RAND, Real pseudo-random number -* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number -* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence -* @code{RANGE}: RANGE, Decimal exponent range -* @code{RANK} : RANK, Rank of a data object -* @code{REAL}: REAL, Convert to real type -* @code{RENAME}: RENAME, Rename a file -* @code{REPEAT}: REPEAT, Repeated string concatenation -* @code{RESHAPE}: RESHAPE, Function to reshape an array -* @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing -* @code{RSHIFT}: RSHIFT, Right shift bits -* @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality -* @code{SCALE}: SCALE, Scale a real value -* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters -* @code{SECNDS}: SECNDS, Time function -* @code{SECOND}: SECOND, CPU time function -* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind -* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind -* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind -* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model -* @code{SHAPE}: SHAPE, Determine the shape of an array -* @code{SHIFTA}: SHIFTA, Right shift with fill -* @code{SHIFTL}: SHIFTL, Left shift -* @code{SHIFTR}: SHIFTR, Right shift -* @code{SIGN}: SIGN, Sign copying function -* @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function) -* @code{SIN}: SIN, Sine function -* @code{SINH}: SINH, Hyperbolic sine function -* @code{SIZE}: SIZE, Function to determine the size of an array -* @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression -* @code{SLEEP}: SLEEP, Sleep for the specified number of seconds -* @code{SPACING}: SPACING, Smallest distance between two numbers of a given type -* @code{SPREAD}: SPREAD, Add a dimension to an array -* @code{SQRT}: SQRT, Square-root function -* @code{SRAND}: SRAND, Reinitialize the random number generator -* @code{STAT}: STAT, Get file status -* @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits -* @code{SUM}: SUM, Sum of array elements -* @code{SYMLNK}: SYMLNK, Create a symbolic link -* @code{SYSTEM}: SYSTEM, Execute a shell command -* @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function -* @code{TAN}: TAN, Tangent function -* @code{TANH}: TANH, Hyperbolic tangent function -* @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image -* @code{TIME}: TIME, Time function -* @code{TIME8}: TIME8, Time function (64-bit) -* @code{TINY}: TINY, Smallest positive number of a real kind -* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer -* @code{TRANSFER}: TRANSFER, Transfer bit patterns -* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two -* @code{TRIM}: TRIM, Remove trailing blank characters of a string -* @code{TTYNAM}: TTYNAM, Get the name of a terminal device. -* @code{UBOUND}: UBOUND, Upper dimension bounds of an array -* @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array -* @code{UMASK}: UMASK, Set the file creation mask -* @code{UNLINK}: UNLINK, Remove a file from the file system -* @code{UNPACK}: UNPACK, Unpack an array of rank one into an array -* @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters -* @code{XOR}: XOR, Bitwise logical exclusive or -@end menu - -@node Introduction to Intrinsics -@section Introduction to intrinsic procedures - -The intrinsic procedures provided by GNU Fortran include all of the -intrinsic procedures required by the Fortran 95 standard, a set of -intrinsic procedures for backwards compatibility with G77, and a -selection of intrinsic procedures from the Fortran 2003 and Fortran 2008 -standards. Any conflict between a description here and a description in -either the Fortran 95 standard, the Fortran 2003 standard or the Fortran -2008 standard is unintentional, and the standard(s) should be considered -authoritative. - -The enumeration of the @code{KIND} type parameter is processor defined in -the Fortran 95 standard. GNU Fortran defines the default integer type and -default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)}, -respectively. The standard mandates that both data types shall have -another kind, which have more precision. On typical target architectures -supported by @command{gfortran}, this kind type parameter is @code{KIND=8}. -Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent. -In the description of generic intrinsic procedures, the kind type parameter -will be specified by @code{KIND=*}, and in the description of specific -names for an intrinsic procedure the kind type parameter will be explicitly -given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for -brevity the optional @code{KIND=} syntax will be omitted. - -Many of the intrinsic 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. - -GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options, -which can be used to restrict the set of intrinsic procedures to a -given standard. By default, @command{gfortran} sets the @option{-std=gnu} -option, and so all intrinsic procedures described here are accepted. There -is one caveat. For a select group of intrinsic procedures, @command{g77} -implemented both a function and a subroutine. Both classes -have been implemented in @command{gfortran} for backwards compatibility -with @command{g77}. It is noted here that these functions and subroutines -cannot be intermixed in a given subprogram. In the descriptions that follow, -the applicable standard for each intrinsic procedure is noted. - - - -@node ABORT -@section @code{ABORT} --- Abort the program -@fnindex ABORT -@cindex program termination, with core dump -@cindex terminate program, with core dump -@cindex core, dump - -@table @asis -@item @emph{Description}: -@code{ABORT} causes immediate termination of the program. On operating -systems that support a core dump, @code{ABORT} will produce a core dump. -It will also print a backtrace, unless @code{-fno-backtrace} is given. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL ABORT} - -@item @emph{Return value}: -Does not return. - -@item @emph{Example}: -@smallexample -program test_abort - integer :: i = 1, j = 2 - if (i /= j) call abort -end program test_abort -@end smallexample - -@item @emph{See also}: -@ref{EXIT}, @ref{KILL}, @ref{BACKTRACE} - -@end table - - - -@node ABS -@section @code{ABS} --- Absolute value -@fnindex ABS -@fnindex CABS -@fnindex DABS -@fnindex IABS -@fnindex ZABS -@fnindex CDABS -@cindex absolute value - -@table @asis -@item @emph{Description}: -@code{ABS(A)} computes the absolute value of @code{A}. - -@item @emph{Standard}: -Fortran 77 and later, has overloads that are GNU extensions - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ABS(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type of the argument shall be an @code{INTEGER}, -@code{REAL}, or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and -kind as the argument except the return value is @code{REAL} for a -@code{COMPLEX} argument. - -@item @emph{Example}: -@smallexample -program test_abs - 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_abs -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later -@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later -@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension -@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension -@end multitable -@end table - - - -@node ACCESS -@section @code{ACCESS} --- Checks file access modes -@fnindex ACCESS -@cindex file system, access mode - -@table @asis -@item @emph{Description}: -@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} -exists, is readable, writable or executable. Except for the -executable check, @code{ACCESS} can be replaced by -Fortran 95's @code{INQUIRE}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = ACCESS(NAME, MODE)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the -file name. Tailing blank are ignored unless the character @code{achar(0)} -is present, then all characters up to and excluding @code{achar(0)} are -used as file name. -@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the -file access mode, may be any concatenation of @code{"r"} (readable), -@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check -for existence. -@end multitable - -@item @emph{Return value}: -Returns a scalar @code{INTEGER}, which is @code{0} if the file is -accessible in the given mode; otherwise or if an invalid argument -has been given for @code{MODE} the value @code{1} is returned. - -@item @emph{Example}: -@smallexample -program access_test - implicit none - character(len=*), parameter :: file = 'test.dat' - character(len=*), parameter :: file2 = 'test.dat '//achar(0) - if(access(file,' ') == 0) print *, trim(file),' is exists' - if(access(file,'r') == 0) print *, trim(file),' is readable' - if(access(file,'w') == 0) print *, trim(file),' is writable' - if(access(file,'x') == 0) print *, trim(file),' is executable' - if(access(file2,'rwx') == 0) & - print *, trim(file2),' is readable, writable and executable' -end program access_test -@end smallexample -@item @emph{Specific names}: -@item @emph{See also}: - -@end table - - - -@node ACHAR -@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence -@fnindex ACHAR -@cindex @acronym{ASCII} collating sequence -@cindex collating sequence, @acronym{ASCII} - -@table @asis -@item @emph{Description}: -@code{ACHAR(I)} returns the character located at position @code{I} -in the @acronym{ASCII} collating sequence. - -@item @emph{Standard}: -Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ACHAR(I [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{CHARACTER} with a length of one. -If the @var{KIND} argument is present, the return value is of the -specified kind and of the default kind otherwise. - -@item @emph{Example}: -@smallexample -program test_achar - character c - c = achar(32) -end program test_achar -@end smallexample - -@item @emph{Note}: -See @ref{ICHAR} for a discussion of converting between numerical values -and formatted string representations. - -@item @emph{See also}: -@ref{CHAR}, @ref{IACHAR}, @ref{ICHAR} - -@end table - - - -@node ACOS -@section @code{ACOS} --- Arccosine function -@fnindex ACOS -@fnindex DACOS -@cindex trigonometric function, cosine, inverse -@cindex cosine, inverse - -@table @asis -@item @emph{Description}: -@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). - -@item @emph{Standard}: -Fortran 77 and later, for a complex argument Fortran 2008 or later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ACOS(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is -less than or equal to one - or the type shall be @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. -The real part of the result is in radians and lies in the range -@math{0 \leq \Re \acos(x) \leq \pi}. - -@item @emph{Example}: -@smallexample -program test_acos - real(8) :: x = 0.866_8 - x = acos(x) -end program test_acos -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -Inverse function: @ref{COS} - -@end table - - - -@node ACOSH -@section @code{ACOSH} --- Inverse hyperbolic cosine function -@fnindex ACOSH -@fnindex DACOSH -@cindex area hyperbolic cosine -@cindex inverse hyperbolic cosine -@cindex hyperbolic function, cosine, inverse -@cindex cosine, hyperbolic, inverse - -@table @asis -@item @emph{Description}: -@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ACOSH(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has the same type and kind as @var{X}. If @var{X} is -complex, the imaginary part of the result is in radians and lies between -@math{ 0 \leq \Im \acosh(x) \leq \pi}. - -@item @emph{Example}: -@smallexample -PROGRAM test_acosh - REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) - WRITE (*,*) ACOSH(x) -END PROGRAM -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable - -@item @emph{See also}: -Inverse function: @ref{COSH} -@end table - - - -@node ADJUSTL -@section @code{ADJUSTL} --- Left adjust a string -@fnindex ADJUSTL -@cindex string, adjust left -@cindex adjust string - -@table @asis -@item @emph{Description}: -@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. -Spaces are inserted at the end of the string as needed. - -@item @emph{Standard}: -Fortran 90 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ADJUSTL(STRING)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab The type shall be @code{CHARACTER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{CHARACTER} and of the same kind as -@var{STRING} where leading spaces are removed and the same number of -spaces are inserted on the end of @var{STRING}. - -@item @emph{Example}: -@smallexample -program test_adjustl - character(len=20) :: str = ' gfortran' - str = adjustl(str) - print *, str -end program test_adjustl -@end smallexample - -@item @emph{See also}: -@ref{ADJUSTR}, @ref{TRIM} -@end table - - - -@node ADJUSTR -@section @code{ADJUSTR} --- Right adjust a string -@fnindex ADJUSTR -@cindex string, adjust right -@cindex adjust string - -@table @asis -@item @emph{Description}: -@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. -Spaces are inserted at the start of the string as needed. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ADJUSTR(STRING)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STR} @tab The type shall be @code{CHARACTER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{CHARACTER} and of the same kind as -@var{STRING} where trailing spaces are removed and the same number of -spaces are inserted at the start of @var{STRING}. - -@item @emph{Example}: -@smallexample -program test_adjustr - character(len=20) :: str = 'gfortran' - str = adjustr(str) - print *, str -end program test_adjustr -@end smallexample - -@item @emph{See also}: -@ref{ADJUSTL}, @ref{TRIM} -@end table - - - -@node AIMAG -@section @code{AIMAG} --- Imaginary part of complex number -@fnindex AIMAG -@fnindex DIMAG -@fnindex IMAG -@fnindex IMAGPART -@cindex complex numbers, imaginary part - -@table @asis -@item @emph{Description}: -@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. -The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided -for compatibility with @command{g77}, and their use in new code is -strongly discouraged. - -@item @emph{Standard}: -Fortran 77 and later, has overloads that are GNU extensions - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = AIMAG(Z)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} with the -kind type parameter of the argument. - -@item @emph{Example}: -@smallexample -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 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension -@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension -@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension -@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension -@end multitable -@end table - - - -@node AINT -@section @code{AINT} --- Truncate to a whole number -@fnindex AINT -@fnindex DINT -@cindex floor -@cindex rounding, floor - -@table @asis -@item @emph{Description}: -@code{AINT(A [, KIND])} truncates its argument to a whole number. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = AINT(A [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type of the argument shall be @code{REAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} with the kind type parameter of the -argument if the optional @var{KIND} is absent; otherwise, the kind -type parameter will be given by @var{KIND}. If the magnitude of -@var{X} is less than one, @code{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 @var{X}. - -@item @emph{Example}: -@smallexample -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 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable -@end table - - - -@node ALARM -@section @code{ALARM} --- Execute a routine after a given delay -@fnindex ALARM -@cindex delayed execution - -@table @asis -@item @emph{Description}: -@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} -to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to -set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is -supplied, it will be returned with the number of seconds remaining until -any previously scheduled alarm was due to be delivered, or zero if there -was no previously scheduled alarm. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL ALARM(SECONDS, HANDLER [, STATUS])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SECONDS} @tab The type of the argument shall be a scalar -@code{INTEGER}. It is @code{INTENT(IN)}. -@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or -@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar -values may be either @code{SIG_IGN=1} to ignore the alarm generated -or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. -@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar -variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. -@end multitable - -@item @emph{Example}: -@smallexample -program test_alarm - external handler_print - integer i - call alarm (3, handler_print, i) - print *, i - call sleep(10) -end program test_alarm -@end smallexample -This will cause the external routine @var{handler_print} to be called -after 3 seconds. -@end table - - - -@node ALL -@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true -@fnindex ALL -@cindex array, apply condition -@cindex array, condition testing - -@table @asis -@item @emph{Description}: -@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} -in the array along dimension @var{DIM}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = ALL(MASK [, DIM])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and -it shall not be scalar. -@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer -with a value that lies between one and the rank of @var{MASK}. -@end multitable - -@item @emph{Return value}: -@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where -the kind type parameter is the same as the kind type parameter of -@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns -an array with the rank of @var{MASK} minus 1. The shape is determined from -the shape of @var{MASK} where the @var{DIM} dimension is elided. - -@table @asis -@item (A) -@code{ALL(MASK)} is true if all elements of @var{MASK} are true. -It also is true if @var{MASK} has zero size; otherwise, it is false. -@item (B) -If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent -to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} -is determined by applying @code{ALL} to the array sections. -@end table - -@item @emph{Example}: -@smallexample -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 -@end smallexample -@end table - - - -@node ALLOCATED -@section @code{ALLOCATED} --- Status of an allocatable entity -@fnindex ALLOCATED -@cindex allocation, status - -@table @asis -@item @emph{Description}: -@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation -status of @var{ARRAY} and @var{SCALAR}, respectively. - -@item @emph{Standard}: -Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable -scalar entities are available in Fortran 2003 and later. - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = ALLOCATED(ARRAY)} -@item @code{RESULT = ALLOCATED(SCALAR)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. -@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. -@end multitable - -@item @emph{Return value}: -The return value is a scalar @code{LOGICAL} with the default logical -kind type parameter. If the argument is allocated, then the result is -@code{.TRUE.}; otherwise, it returns @code{.FALSE.} - -@item @emph{Example}: -@smallexample -program test_allocated - integer :: i = 4 - real(4), allocatable :: x(:) - if (.not. allocated(x)) allocate(x(i)) -end program test_allocated -@end smallexample -@end table - - - -@node AND -@section @code{AND} --- Bitwise logical AND -@fnindex AND -@cindex bitwise logical and -@cindex logical and, bitwise - -@table @asis -@item @emph{Description}: -Bitwise logical @code{AND}. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. For integer arguments, programmers should consider -the use of the @ref{IAND} intrinsic defined by the Fortran standard. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = AND(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be either a scalar @code{INTEGER} -type or a scalar @code{LOGICAL} type. -@item @var{J} @tab The type shall be the same as the type of @var{I}. -@end multitable - -@item @emph{Return value}: -The return type is either a scalar @code{INTEGER} or a scalar -@code{LOGICAL}. If the kind type parameters differ, then the -smaller kind type is implicitly converted to larger kind, and the -return has the larger kind. - -@item @emph{Example}: -@smallexample -PROGRAM test_and - LOGICAL :: T = .TRUE., F = .FALSE. - INTEGER :: a, b - DATA a / Z'F' /, b / Z'3' / - - WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) - WRITE (*,*) AND(a, b) -END PROGRAM -@end smallexample - -@item @emph{See also}: -Fortran 95 elemental function: @ref{IAND} -@end table - - - -@node ANINT -@section @code{ANINT} --- Nearest whole number -@fnindex ANINT -@fnindex DNINT -@cindex ceiling -@cindex rounding, ceiling - -@table @asis -@item @emph{Description}: -@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ANINT(A [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type of the argument shall be @code{REAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type real with the kind type parameter of the -argument if the optional @var{KIND} is absent; otherwise, the kind -type parameter will be given by @var{KIND}. If @var{A} is greater than -zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is -less than or equal to zero then it returns @code{AINT(X-0.5)}. - -@item @emph{Example}: -@smallexample -program test_anint - real(4) x4 - real(8) x8 - x4 = 1.234E0_4 - x8 = 4.321_8 - print *, anint(x4), dnint(x8) - x8 = anint(x4,8) -end program test_anint -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable -@end table - - - -@node ANY -@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true -@fnindex ANY -@cindex array, apply condition -@cindex array, condition testing - -@table @asis -@item @emph{Description}: -@code{ANY(MASK [, DIM])} determines if any of the values in the logical array -@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = ANY(MASK [, DIM])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and -it shall not be scalar. -@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer -with a value that lies between one and the rank of @var{MASK}. -@end multitable - -@item @emph{Return value}: -@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where -the kind type parameter is the same as the kind type parameter of -@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns -an array with the rank of @var{MASK} minus 1. The shape is determined from -the shape of @var{MASK} where the @var{DIM} dimension is elided. - -@table @asis -@item (A) -@code{ANY(MASK)} is true if any element of @var{MASK} is true; -otherwise, it is false. It also is false if @var{MASK} has zero size. -@item (B) -If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent -to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} -is determined by applying @code{ANY} to the array sections. -@end table - -@item @emph{Example}: -@smallexample -program test_any - logical l - l = any((/.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 *, any(a .eq. b, 1) - print *, any(a .eq. b, 2) - end subroutine section -end program test_any -@end smallexample -@end table - - - -@node ASIN -@section @code{ASIN} --- Arcsine function -@fnindex ASIN -@fnindex DASIN -@cindex trigonometric function, sine, inverse -@cindex sine, inverse - -@table @asis -@item @emph{Description}: -@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). - -@item @emph{Standard}: -Fortran 77 and later, for a complex argument Fortran 2008 or later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ASIN(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is -less than or equal to one - or be @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. -The real part of the result is in radians and lies in the range -@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. - -@item @emph{Example}: -@smallexample -program test_asin - real(8) :: x = 0.866_8 - x = asin(x) -end program test_asin -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -Inverse function: @ref{SIN} - -@end table - - - -@node ASINH -@section @code{ASINH} --- Inverse hyperbolic sine function -@fnindex ASINH -@fnindex DASINH -@cindex area hyperbolic sine -@cindex inverse hyperbolic sine -@cindex hyperbolic function, sine, inverse -@cindex sine, hyperbolic, inverse - -@table @asis -@item @emph{Description}: -@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ASINH(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. If @var{X} is -complex, the imaginary part of the result is in radians and lies between -@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. - -@item @emph{Example}: -@smallexample -PROGRAM test_asinh - REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) - WRITE (*,*) ASINH(x) -END PROGRAM -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. -@end multitable - -@item @emph{See also}: -Inverse function: @ref{SINH} -@end table - - - -@node ASSOCIATED -@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair -@fnindex ASSOCIATED -@cindex pointer, status -@cindex association status - -@table @asis -@item @emph{Description}: -@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer -@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = ASSOCIATED(POINTER [, TARGET])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute -and it can be of any type. -@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or -a target. It must have the same type, kind type parameter, and -array rank as @var{POINTER}. -@end multitable -The association status of neither @var{POINTER} nor @var{TARGET} shall be -undefined. - -@item @emph{Return value}: -@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. -There are several cases: -@table @asis -@item (A) When the optional @var{TARGET} is not present then -@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. -@item (B) If @var{TARGET} is present and a scalar target, the result is true if -@var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is -disassociated, the result is false. -@item (C) If @var{TARGET} is present and an array target, the result is true if -@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, -are arrays whose elements are not zero-sized storage sequences, and -@var{TARGET} and @var{POINTER} occupy the same storage units in array element -order. -As in case(B), the result is false, if @var{POINTER} is disassociated. -@item (D) If @var{TARGET} is present and an scalar pointer, the result is true -if @var{TARGET} is associated with @var{POINTER}, the target associated with -@var{TARGET} are not zero-sized storage sequences and occupy the same storage -units. -The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. -@item (E) If @var{TARGET} is present and an array pointer, the result is true if -target associated with @var{POINTER} and the target associated with @var{TARGET} -have the same shape, are not zero-sized arrays, are arrays whose elements are -not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy -the same storage units in array element order. -The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. -@end table - -@item @emph{Example}: -@smallexample -program test_associated - implicit none - real, target :: tgt(2) = (/1., 2./) - real, pointer :: ptr(:) - ptr => tgt - if (associated(ptr) .eqv. .false.) call abort - if (associated(ptr,tgt) .eqv. .false.) call abort -end program test_associated -@end smallexample - -@item @emph{See also}: -@ref{NULL} -@end table - - - -@node ATAN -@section @code{ATAN} --- Arctangent function -@fnindex ATAN -@fnindex DATAN -@cindex trigonometric function, tangent, inverse -@cindex tangent, inverse - -@table @asis -@item @emph{Description}: -@code{ATAN(X)} computes the arctangent of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later, for a complex argument and for two arguments -Fortran 2008 or later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = ATAN(X)} -@item @code{RESULT = ATAN(Y, X)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; -if @var{Y} is present, @var{X} shall be REAL. -@item @var{Y} shall be of the same type and kind as @var{X}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. -If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. -Otherwise, it the arcus tangent of @var{X}, where the real part of -the result is in radians and lies in the range -@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. - -@item @emph{Example}: -@smallexample -program test_atan - real(8) :: x = 2.866_8 - x = atan(x) -end program test_atan -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -Inverse function: @ref{TAN} - -@end table - - - -@node ATAN2 -@section @code{ATAN2} --- Arctangent function -@fnindex ATAN2 -@fnindex DATAN2 -@cindex trigonometric function, tangent, inverse -@cindex tangent, inverse - -@table @asis -@item @emph{Description}: -@code{ATAN2(Y, X)} computes the principal value of the argument -function of the complex number @math{X + i Y}. This function can -be used to transform from Cartesian into polar coordinates and -allows to determine the angle in the correct quadrant. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ATAN2(Y, X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{Y} @tab The type shall be @code{REAL}. -@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. -If @var{Y} is zero, then @var{X} must be nonzero. -@end multitable - -@item @emph{Return value}: -The return value has the same type and kind type parameter as @var{Y}. It -is the principal value of the complex number @math{X + i Y}. If @var{X} -is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. -The sign is positive if @var{Y} is positive. If @var{Y} is zero, then -the return value is zero if @var{X} is strictly positive, @math{\pi} if -@var{X} is negative and @var{Y} is positive zero (or the processor does -not handle signed zeros), and @math{-\pi} if @var{X} is negative and -@var{Y} is negative zero. Finally, if @var{X} is zero, then the -magnitude of the result is @math{\pi/2}. - -@item @emph{Example}: -@smallexample -program test_atan2 - real(4) :: x = 1.e0_4, y = 0.5e0_4 - x = atan2(y,x) -end program test_atan2 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable -@end table - - - -@node ATANH -@section @code{ATANH} --- Inverse hyperbolic tangent function -@fnindex ATANH -@fnindex DATANH -@cindex area hyperbolic tangent -@cindex inverse hyperbolic tangent -@cindex hyperbolic function, tangent, inverse -@cindex tangent, hyperbolic, inverse - -@table @asis -@item @emph{Description}: -@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ATANH(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has same type and kind as @var{X}. If @var{X} is -complex, the imaginary part of the result is in radians and lies between -@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. - -@item @emph{Example}: -@smallexample -PROGRAM test_atanh - REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) - WRITE (*,*) ATANH(x) -END PROGRAM -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable - -@item @emph{See also}: -Inverse function: @ref{TANH} -@end table - - - -@node ATOMIC_DEFINE -@section @code{ATOMIC_DEFINE} --- Setting a variable atomically -@fnindex ATOMIC_DEFINE -@cindex Atomic subroutine, define - -@table @asis -@item @emph{Description}: -@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value -@var{VALUE} atomically. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Atomic subroutine - -@item @emph{Syntax}: -@code{CALL ATOMIC_DEFINE(ATOM, VALUE)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer - type with @code{ATOMIC_INT_KIND} kind or logical type - with @code{ATOMIC_LOGICAL_KIND} kind. -@item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind - is different, the value is converted to the kind of - @var{ATOM}. -@end multitable - -@item @emph{Example}: -@smallexample -program atomic - use iso_fortran_env - integer(atomic_int_kind) :: atom[*] - call atomic_define (atom[1], this_image()) -end program atomic -@end smallexample - -@item @emph{See also}: -@ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV} -@end table - - - -@node ATOMIC_REF -@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically -@fnindex ATOMIC_REF -@cindex Atomic subroutine, reference - -@table @asis -@item @emph{Description}: -@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the -variable @var{ATOM} to @var{VALUE}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Atomic subroutine - -@item @emph{Syntax}: -@code{CALL ATOMIC_REF(VALUE, ATOM)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind - is different, the value is converted to the kind of - @var{ATOM}. -@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer - type with @code{ATOMIC_INT_KIND} kind or logical type - with @code{ATOMIC_LOGICAL_KIND} kind. -@end multitable - -@item @emph{Example}: -@smallexample -program atomic - use iso_fortran_env - logical(atomic_logical_kind) :: atom[*] - logical :: val - call atomic_ref (atom, .false.) - ! ... - call atomic_ref (atom, val) - if (val) then - print *, "Obtained" - end if -end program atomic -@end smallexample - -@item @emph{See also}: -@ref{ATOMIC_DEFINE}, @ref{ISO_FORTRAN_ENV} -@end table - - - -@node BACKTRACE -@section @code{BACKTRACE} --- Show a backtrace -@fnindex BACKTRACE -@cindex backtrace - -@table @asis -@item @emph{Description}: -@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program -execution continues normally afterwards. The backtrace information is printed -to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. - -@item @emph{Standard}: -GNU Extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL BACKTRACE} - -@item @emph{Arguments}: -None - -@item @emph{See also}: -@ref{ABORT} -@end table - - - -@node BESSEL_J0 -@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 -@fnindex BESSEL_J0 -@fnindex BESJ0 -@fnindex DBESJ0 -@cindex Bessel function, first kind - -@table @asis -@item @emph{Description}: -@code{BESSEL_J0(X)} computes the Bessel function of the first kind of -order 0 of @var{X}. This function is available under the name -@code{BESJ0} as a GNU extension. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BESSEL_J0(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} and lies in the -range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same -kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_besj0 - real(8) :: x = 0.0_8 - x = bessel_j0(x) -end program test_besj0 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable -@end table - - - -@node BESSEL_J1 -@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 -@fnindex BESSEL_J1 -@fnindex BESJ1 -@fnindex DBESJ1 -@cindex Bessel function, first kind - -@table @asis -@item @emph{Description}: -@code{BESSEL_J1(X)} computes the Bessel function of the first kind of -order 1 of @var{X}. This function is available under the name -@code{BESJ1} as a GNU extension. - -@item @emph{Standard}: -Fortran 2008 - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BESSEL_J1(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} and it lies in the -range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same -kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_besj1 - real(8) :: x = 1.0_8 - x = bessel_j1(x) -end program test_besj1 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable -@end table - - - -@node BESSEL_JN -@section @code{BESSEL_JN} --- Bessel function of the first kind -@fnindex BESSEL_JN -@fnindex BESJN -@fnindex DBESJN -@cindex Bessel function, first kind - -@table @asis -@item @emph{Description}: -@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of -order @var{N} of @var{X}. This function is available under the name -@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, -their ranks and shapes shall conform. - -@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions -of the first kind of the orders @var{N1} to @var{N2}. - -@item @emph{Standard}: -Fortran 2008 and later, negative @var{N} is allowed as GNU extension - -@item @emph{Class}: -Elemental function, except for the transformational function -@code{BESSEL_JN(N1, N2, X)} - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = BESSEL_JN(N, X)} -@item @code{RESULT = BESSEL_JN(N1, N2, X)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. -@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. -@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. -@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; -for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type @code{REAL}. It has the same -kind as @var{X}. - -@item @emph{Note}: -The transformational function uses a recurrence algorithm which might, -for some values of @var{X}, lead to different results than calls to -the elemental function. - -@item @emph{Example}: -@smallexample -program test_besjn - real(8) :: x = 1.0_8 - x = bessel_jn(5,x) -end program test_besjn -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension -@item @tab @code{REAL(8) X} @tab @tab -@end multitable -@end table - - - -@node BESSEL_Y0 -@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 -@fnindex BESSEL_Y0 -@fnindex BESY0 -@fnindex DBESY0 -@cindex Bessel function, second kind - -@table @asis -@item @emph{Description}: -@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of -order 0 of @var{X}. This function is available under the name -@code{BESY0} as a GNU extension. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BESSEL_Y0(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar. -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type @code{REAL}. It has the same -kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_besy0 - real(8) :: x = 0.0_8 - x = bessel_y0(x) -end program test_besy0 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable -@end table - - - -@node BESSEL_Y1 -@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 -@fnindex BESSEL_Y1 -@fnindex BESY1 -@fnindex DBESY1 -@cindex Bessel function, second kind - -@table @asis -@item @emph{Description}: -@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of -order 1 of @var{X}. This function is available under the name -@code{BESY1} as a GNU extension. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BESSEL_Y1(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar. -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type @code{REAL}. It has the same -kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_besy1 - real(8) :: x = 1.0_8 - x = bessel_y1(x) -end program test_besy1 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable -@end table - - - -@node BESSEL_YN -@section @code{BESSEL_YN} --- Bessel function of the second kind -@fnindex BESSEL_YN -@fnindex BESYN -@fnindex DBESYN -@cindex Bessel function, second kind - -@table @asis -@item @emph{Description}: -@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of -order @var{N} of @var{X}. This function is available under the name -@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, -their ranks and shapes shall conform. - -@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions -of the first kind of the orders @var{N1} to @var{N2}. - -@item @emph{Standard}: -Fortran 2008 and later, negative @var{N} is allowed as GNU extension - -@item @emph{Class}: -Elemental function, except for the transformational function -@code{BESSEL_YN(N1, N2, X)} - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = BESSEL_YN(N, X)} -@item @code{RESULT = BESSEL_YN(N1, N2, X)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . -@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. -@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. -@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; -for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type @code{REAL}. It has the same -kind as @var{X}. - -@item @emph{Note}: -The transformational function uses a recurrence algorithm which might, -for some values of @var{X}, lead to different results than calls to -the elemental function. - -@item @emph{Example}: -@smallexample -program test_besyn - real(8) :: x = 1.0_8 - x = bessel_yn(5,x) -end program test_besyn -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension -@item @tab @code{REAL(8) X} @tab @tab -@end multitable -@end table - - - -@node BGE -@section @code{BGE} --- Bitwise greater than or equal to -@fnindex BGE -@cindex bitwise comparison - -@table @asis -@item @emph{Description}: -Determines whether an integral is a bitwise greater than or equal to -another. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BGE(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of @code{INTEGER} type. -@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind -as @var{I}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{LOGICAL} and of the default kind. - -@item @emph{See also}: -@ref{BGT}, @ref{BLE}, @ref{BLT} -@end table - - - -@node BGT -@section @code{BGT} --- Bitwise greater than -@fnindex BGT -@cindex bitwise comparison - -@table @asis -@item @emph{Description}: -Determines whether an integral is a bitwise greater than another. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BGT(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of @code{INTEGER} type. -@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind -as @var{I}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{LOGICAL} and of the default kind. - -@item @emph{See also}: -@ref{BGE}, @ref{BLE}, @ref{BLT} -@end table - - - -@node BIT_SIZE -@section @code{BIT_SIZE} --- Bit size inquiry function -@fnindex BIT_SIZE -@cindex bits, number of -@cindex size of a variable, in bits - -@table @asis -@item @emph{Description}: -@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) -represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is -independent of the actual value of @var{I}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = BIT_SIZE(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} - -@item @emph{Example}: -@smallexample -program test_bit_size - integer :: i = 123 - integer :: size - size = bit_size(i) - print *, size -end program test_bit_size -@end smallexample -@end table - - - -@node BLE -@section @code{BLE} --- Bitwise less than or equal to -@fnindex BLE -@cindex bitwise comparison - -@table @asis -@item @emph{Description}: -Determines whether an integral is a bitwise less than or equal to -another. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BLE(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of @code{INTEGER} type. -@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind -as @var{I}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{LOGICAL} and of the default kind. - -@item @emph{See also}: -@ref{BGT}, @ref{BGE}, @ref{BLT} -@end table - - - -@node BLT -@section @code{BLT} --- Bitwise less than -@fnindex BLT -@cindex bitwise comparison - -@table @asis -@item @emph{Description}: -Determines whether an integral is a bitwise less than another. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BLT(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of @code{INTEGER} type. -@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind -as @var{I}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{LOGICAL} and of the default kind. - -@item @emph{See also}: -@ref{BGE}, @ref{BGT}, @ref{BLE} -@end table - - - -@node BTEST -@section @code{BTEST} --- Bit test function -@fnindex BTEST -@cindex bits, testing - -@table @asis -@item @emph{Description}: -@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} -in @var{I} is set. The counting of the bits starts at 0. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = BTEST(I, POS)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{POS} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{LOGICAL} - -@item @emph{Example}: -@smallexample -program test_btest - integer :: i = 32768 + 1024 + 64 - integer :: pos - logical :: bool - do pos=0,16 - bool = btest(i, pos) - print *, pos, bool - end do -end program test_btest -@end smallexample -@end table - - -@node C_ASSOCIATED -@section @code{C_ASSOCIATED} --- Status of a C pointer -@fnindex C_ASSOCIATED -@cindex association status, C pointer -@cindex pointer, C association status - -@table @asis -@item @emph{Description}: -@code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer -@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. -@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{LOGICAL}; it is @code{.false.} if either -@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} -point to different addresses. - -@item @emph{Example}: -@smallexample -subroutine association_test(a,b) - use iso_c_binding, only: c_associated, c_loc, c_ptr - implicit none - real, pointer :: a - type(c_ptr) :: b - if(c_associated(b, c_loc(a))) & - stop 'b and a do not point to same target' -end subroutine association_test -@end smallexample - -@item @emph{See also}: -@ref{C_LOC}, @ref{C_FUNLOC} -@end table - - -@node C_F_POINTER -@section @code{C_F_POINTER} --- Convert C into Fortran pointer -@fnindex C_F_POINTER -@cindex pointer, convert C to Fortran - -@table @asis -@item @emph{Description}: -@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer -@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is -@code{INTENT(IN)}. -@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is -@code{INTENT(OUT)}. -@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} -with @code{INTENT(IN)}. It shall be present -if and only if @var{fptr} is an array. The size -must be equal to the rank of @var{fptr}. -@end multitable - -@item @emph{Example}: -@smallexample -program main - use iso_c_binding - implicit none - interface - subroutine my_routine(p) bind(c,name='myC_func') - import :: c_ptr - type(c_ptr), intent(out) :: p - end subroutine - end interface - type(c_ptr) :: cptr - real,pointer :: a(:) - call my_routine(cptr) - call c_f_pointer(cptr, a, [12]) -end program main -@end smallexample - -@item @emph{See also}: -@ref{C_LOC}, @ref{C_F_PROCPOINTER} -@end table - - -@node C_F_PROCPOINTER -@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer -@fnindex C_F_PROCPOINTER -@cindex pointer, C address of pointers - -@table @asis -@item @emph{Description}: -@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer -@var{CPTR} to the Fortran procedure pointer @var{FPTR}. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL C_F_PROCPOINTER(cptr, fptr)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is -@code{INTENT(IN)}. -@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is -@code{INTENT(OUT)}. -@end multitable - -@item @emph{Example}: -@smallexample -program main - use iso_c_binding - implicit none - abstract interface - function func(a) - import :: c_float - real(c_float), intent(in) :: a - real(c_float) :: func - end function - end interface - interface - function getIterFunc() bind(c,name="getIterFunc") - import :: c_funptr - type(c_funptr) :: getIterFunc - end function - end interface - type(c_funptr) :: cfunptr - procedure(func), pointer :: myFunc - cfunptr = getIterFunc() - call c_f_procpointer(cfunptr, myFunc) -end program main -@end smallexample - -@item @emph{See also}: -@ref{C_LOC}, @ref{C_F_POINTER} -@end table - - -@node C_FUNLOC -@section @code{C_FUNLOC} --- Obtain the C address of a procedure -@fnindex C_FUNLOC -@cindex pointer, C address of procedures - -@table @asis -@item @emph{Description}: -@code{C_FUNLOC(x)} determines the C address of the argument. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = C_FUNLOC(x)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{x} @tab Interoperable function or pointer to such function. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{C_FUNPTR} and contains the C address -of the argument. - -@item @emph{Example}: -@smallexample -module x - use iso_c_binding - implicit none -contains - subroutine sub(a) bind(c) - real(c_float) :: a - a = sqrt(a)+5.0 - end subroutine sub -end module x -program main - use iso_c_binding - use x - implicit none - interface - subroutine my_routine(p) bind(c,name='myC_func') - import :: c_funptr - type(c_funptr), intent(in) :: p - end subroutine - end interface - call my_routine(c_funloc(sub)) -end program main -@end smallexample - -@item @emph{See also}: -@ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} -@end table - - -@node C_LOC -@section @code{C_LOC} --- Obtain the C address of an object -@fnindex C_LOC -@cindex procedure pointer, convert C to Fortran - -@table @asis -@item @emph{Description}: -@code{C_LOC(X)} determines the C address of the argument. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = C_LOC(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .10 .75 -@item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters. - -@end multitable - -@item @emph{Return value}: -The return value is of type @code{C_PTR} and contains the C address -of the argument. - -@item @emph{Example}: -@smallexample -subroutine association_test(a,b) - use iso_c_binding, only: c_associated, c_loc, c_ptr - implicit none - real, pointer :: a - type(c_ptr) :: b - if(c_associated(b, c_loc(a))) & - stop 'b and a do not point to same target' -end subroutine association_test -@end smallexample - -@item @emph{See also}: -@ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} -@end table - - -@node C_SIZEOF -@section @code{C_SIZEOF} --- Size in bytes of an expression -@fnindex C_SIZEOF -@cindex expression size -@cindex size of an expression - -@table @asis -@item @emph{Description}: -@code{C_SIZEOF(X)} calculates the number of bytes of storage the -expression @code{X} occupies. - -@item @emph{Standard}: -Fortran 2008 - -@item @emph{Class}: -Inquiry function of the module @code{ISO_C_BINDING} - -@item @emph{Syntax}: -@code{N = C_SIZEOF(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The argument shall be an interoperable data entity. -@end multitable - -@item @emph{Return value}: -The return value is of type integer and of the system-dependent kind -@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the -number of bytes occupied by the argument. If the argument has the -@code{POINTER} attribute, the number of bytes of the storage area pointed -to is returned. If the argument is of a derived type with @code{POINTER} -or @code{ALLOCATABLE} components, the return value does not account for -the sizes of the data pointed to by these components. - -@item @emph{Example}: -@smallexample - use iso_c_binding - integer(c_int) :: i - real(c_float) :: r, s(5) - print *, (c_sizeof(s)/c_sizeof(r) == 5) - end -@end smallexample -The example will print @code{.TRUE.} unless you are using a platform -where default @code{REAL} variables are unusually padded. - -@item @emph{See also}: -@ref{SIZEOF}, @ref{STORAGE_SIZE} -@end table - - -@node CEILING -@section @code{CEILING} --- Integer ceiling function -@fnindex CEILING -@cindex ceiling -@cindex rounding, ceiling - -@table @asis -@item @emph{Description}: -@code{CEILING(A)} returns the least integer greater than or equal to @var{A}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = CEILING(A [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type shall be @code{REAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present -and a default-kind @code{INTEGER} otherwise. - -@item @emph{Example}: -@smallexample -program test_ceiling - real :: x = 63.29 - real :: y = -63.59 - print *, ceiling(x) ! returns 64 - print *, ceiling(y) ! returns -63 -end program test_ceiling -@end smallexample - -@item @emph{See also}: -@ref{FLOOR}, @ref{NINT} - -@end table - - - -@node CHAR -@section @code{CHAR} --- Character conversion function -@fnindex CHAR -@cindex conversion, to character - -@table @asis -@item @emph{Description}: -@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = CHAR(I [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{CHARACTER(1)} - -@item @emph{Example}: -@smallexample -program test_char - integer :: i = 74 - character(1) :: c - c = char(i) - print *, i, c ! returns 'J' -end program test_char -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later -@end multitable - -@item @emph{Note}: -See @ref{ICHAR} for a discussion of converting between numerical values -and formatted string representations. - -@item @emph{See also}: -@ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR} - -@end table - - - -@node CHDIR -@section @code{CHDIR} --- Change working directory -@fnindex CHDIR -@cindex system, working directory - -@table @asis -@item @emph{Description}: -Change current working directory to a specified path. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL CHDIR(NAME [, STATUS])} -@item @code{STATUS = CHDIR(NAME)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NAME} @tab The type shall be @code{CHARACTER} of default -kind and shall specify a valid path within the file system. -@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default -kind. Returns 0 on success, and a system specific and nonzero error code -otherwise. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_chdir - CHARACTER(len=255) :: path - CALL getcwd(path) - WRITE(*,*) TRIM(path) - CALL chdir("/tmp") - CALL getcwd(path) - WRITE(*,*) TRIM(path) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{GETCWD} -@end table - - - -@node CHMOD -@section @code{CHMOD} --- Change access permissions of files -@fnindex CHMOD -@cindex file system, change access mode - -@table @asis -@item @emph{Description}: -@code{CHMOD} changes the permissions of a file. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL CHMOD(NAME, MODE[, STATUS])} -@item @code{STATUS = CHMOD(NAME, MODE)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 - -@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the -file name. Trailing blanks are ignored unless the character -@code{achar(0)} is present, then all characters up to and excluding -@code{achar(0)} are used as the file name. - -@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the -file permission. @var{MODE} uses the same syntax as the @code{chmod} utility -as defined by the POSIX standard. The argument shall either be a string of -a nonnegative octal number or a symbolic mode. - -@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is -@code{0} on success and nonzero otherwise. -@end multitable - -@item @emph{Return value}: -In either syntax, @var{STATUS} is set to @code{0} on success and nonzero -otherwise. - -@item @emph{Example}: -@code{CHMOD} as subroutine -@smallexample -program chmod_test - implicit none - integer :: status - call chmod('test.dat','u+x',status) - print *, 'Status: ', status -end program chmod_test -@end smallexample -@code{CHMOD} as function: -@smallexample -program chmod_test - implicit none - integer :: status - status = chmod('test.dat','u+x') - print *, 'Status: ', status -end program chmod_test -@end smallexample - -@end table - - - -@node CMPLX -@section @code{CMPLX} --- Complex conversion function -@fnindex CMPLX -@cindex complex numbers, conversion to -@cindex conversion, to complex - -@table @asis -@item @emph{Description}: -@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to -the real component. If @var{Y} is present it is converted to the imaginary -component. If @var{Y} is not present then the imaginary component is set to -0.0. If @var{X} is complex then @var{Y} must not be present. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = CMPLX(X [, Y [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, -or @code{COMPLEX}. -@item @var{Y} @tab (Optional; only allowed if @var{X} is not -@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of @code{COMPLEX} type, with a kind equal to -@var{KIND} if it is specified. If @var{KIND} is not specified, the -result is of the default @code{COMPLEX} kind, regardless of the kinds of -@var{X} and @var{Y}. - -@item @emph{Example}: -@smallexample -program test_cmplx - integer :: i = 42 - real :: x = 3.14 - complex :: z - z = cmplx(i, x) - print *, z, cmplx(x) -end program test_cmplx -@end smallexample - -@item @emph{See also}: -@ref{COMPLEX} -@end table - - - -@node COMMAND_ARGUMENT_COUNT -@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments -@fnindex COMMAND_ARGUMENT_COUNT -@cindex command-line arguments -@cindex command-line arguments, number of -@cindex arguments, to program - -@table @asis -@item @emph{Description}: -@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the -command line when the containing program was invoked. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = COMMAND_ARGUMENT_COUNT()} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item None -@end multitable - -@item @emph{Return value}: -The return value is an @code{INTEGER} of default kind. - -@item @emph{Example}: -@smallexample -program test_command_argument_count - integer :: count - count = command_argument_count() - print *, count -end program test_command_argument_count -@end smallexample - -@item @emph{See also}: -@ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT} -@end table - - - -@node COMPILER_OPTIONS -@section @code{COMPILER_OPTIONS} --- Options passed to the compiler -@fnindex COMPILER_OPTIONS -@cindex flags inquiry function -@cindex options inquiry function -@cindex compiler flags inquiry function - -@table @asis -@item @emph{Description}: -@code{COMPILER_OPTIONS} returns a string with the options used for -compiling. - -@item @emph{Standard}: -Fortran 2008 - -@item @emph{Class}: -Inquiry function of the module @code{ISO_FORTRAN_ENV} - -@item @emph{Syntax}: -@code{STR = COMPILER_OPTIONS()} - -@item @emph{Arguments}: -None. - -@item @emph{Return value}: -The return value is a default-kind string with system-dependent length. -It contains the compiler flags used to compile the file, which called -the @code{COMPILER_OPTIONS} intrinsic. - -@item @emph{Example}: -@smallexample - use iso_fortran_env - print '(4a)', 'This file was compiled by ', & - compiler_version(), ' using the options ', & - compiler_options() - end -@end smallexample - -@item @emph{See also}: -@ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV} -@end table - - - -@node COMPILER_VERSION -@section @code{COMPILER_VERSION} --- Compiler version string -@fnindex COMPILER_VERSION -@cindex compiler, name and version -@cindex version of the compiler - -@table @asis -@item @emph{Description}: -@code{COMPILER_VERSION} returns a string with the name and the -version of the compiler. - -@item @emph{Standard}: -Fortran 2008 - -@item @emph{Class}: -Inquiry function of the module @code{ISO_FORTRAN_ENV} - -@item @emph{Syntax}: -@code{STR = COMPILER_VERSION()} - -@item @emph{Arguments}: -None. - -@item @emph{Return value}: -The return value is a default-kind string with system-dependent length. -It contains the name of the compiler and its version number. - -@item @emph{Example}: -@smallexample - use iso_fortran_env - print '(4a)', 'This file was compiled by ', & - compiler_version(), ' using the options ', & - compiler_options() - end -@end smallexample - -@item @emph{See also}: -@ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV} -@end table - - - -@node COMPLEX -@section @code{COMPLEX} --- Complex conversion function -@fnindex COMPLEX -@cindex complex numbers, conversion to -@cindex conversion, to complex - -@table @asis -@item @emph{Description}: -@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted -to the real component and @var{Y} is converted to the imaginary -component. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = COMPLEX(X, Y)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. -@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. -@end multitable - -@item @emph{Return value}: -If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return -value is of default @code{COMPLEX} type. - -If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} -type and one is of @code{INTEGER} type, then the return value is of -@code{COMPLEX} type with a kind equal to that of the @code{REAL} -argument with the highest precision. - -@item @emph{Example}: -@smallexample -program test_complex - integer :: i = 42 - real :: x = 3.14 - print *, complex(i, x) -end program test_complex -@end smallexample - -@item @emph{See also}: -@ref{CMPLX} -@end table - - - -@node CONJG -@section @code{CONJG} --- Complex conjugate function -@fnindex CONJG -@fnindex DCONJG -@cindex complex conjugate - -@table @asis -@item @emph{Description}: -@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} -then the result is @code{(x, -y)} - -@item @emph{Standard}: -Fortran 77 and later, has overloads that are GNU extensions - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{Z = CONJG(Z)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{Z} @tab The type shall be @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{COMPLEX}. - -@item @emph{Example}: -@smallexample -program test_conjg - complex :: z = (2.0, 3.0) - complex(8) :: dz = (2.71_8, -3.14_8) - z= conjg(z) - print *, z - dz = dconjg(dz) - print *, dz -end program test_conjg -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension -@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension -@end multitable -@end table - - - -@node COS -@section @code{COS} --- Cosine function -@fnindex COS -@fnindex DCOS -@fnindex CCOS -@fnindex ZCOS -@fnindex CDCOS -@cindex trigonometric function, cosine -@cindex cosine - -@table @asis -@item @emph{Description}: -@code{COS(X)} computes the cosine of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later, has overloads that are GNU extensions - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = COS(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or -@code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. The real part -of the result is in radians. If @var{X} is of the type @code{REAL}, -the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. - -@item @emph{Example}: -@smallexample -program test_cos - real :: x = 0.0 - x = cos(x) -end program test_cos -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later -@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later -@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension -@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension -@end multitable - -@item @emph{See also}: -Inverse function: @ref{ACOS} - -@end table - - - -@node COSH -@section @code{COSH} --- Hyperbolic cosine function -@fnindex COSH -@fnindex DCOSH -@cindex hyperbolic cosine -@cindex hyperbolic function, cosine -@cindex cosine, hyperbolic - -@table @asis -@item @emph{Description}: -@code{COSH(X)} computes the hyperbolic cosine of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later, for a complex argument Fortran 2008 or later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{X = COSH(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has same type and kind as @var{X}. If @var{X} is -complex, the imaginary part of the result is in radians. If @var{X} -is @code{REAL}, the return value has a lower bound of one, -@math{\cosh (x) \geq 1}. - -@item @emph{Example}: -@smallexample -program test_cosh - real(8) :: x = 1.0_8 - x = cosh(x) -end program test_cosh -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -Inverse function: @ref{ACOSH} - -@end table - - - -@node COUNT -@section @code{COUNT} --- Count function -@fnindex COUNT -@cindex array, conditionally count elements -@cindex array, element counting -@cindex array, number of elements - -@table @asis -@item @emph{Description}: - -Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, -or, if the @var{DIM} argument is supplied, counts the number of -elements along each row of the array in the @var{DIM} direction. -If the array has zero size, or all of the elements of @var{MASK} are -@code{.FALSE.}, then the result is @code{0}. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = COUNT(MASK [, DIM, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{MASK} @tab The type shall be @code{LOGICAL}. -@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. -If @var{DIM} is present, the result is an array with a rank one less -than the rank of @var{ARRAY}, and a size corresponding to the shape -of @var{ARRAY} with the @var{DIM} dimension removed. - -@item @emph{Example}: -@smallexample -program test_count - integer, dimension(2,3) :: a, b - logical, dimension(2,3) :: mask - a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) - b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) - print '(3i3)', a(1,:) - print '(3i3)', a(2,:) - print * - print '(3i3)', b(1,:) - print '(3i3)', b(2,:) - print * - mask = a.ne.b - print '(3l3)', mask(1,:) - print '(3l3)', mask(2,:) - print * - print '(3i3)', count(mask) - print * - print '(3i3)', count(mask, 1) - print * - print '(3i3)', count(mask, 2) -end program test_count -@end smallexample -@end table - - - -@node CPU_TIME -@section @code{CPU_TIME} --- CPU elapsed time in seconds -@fnindex CPU_TIME -@cindex time, elapsed - -@table @asis -@item @emph{Description}: -Returns a @code{REAL} value representing the elapsed CPU time in -seconds. This is useful for testing segments of code to determine -execution time. - -If a time source is available, time will be reported with microsecond -resolution. If no time source is available, @var{TIME} is set to -@code{-1.0}. - -Note that @var{TIME} may contain a, system dependent, arbitrary offset -and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute -value is meaningless, only differences between subsequent calls to -this subroutine, as shown in the example below, should be used. - - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL CPU_TIME(TIME)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. -@end multitable - -@item @emph{Return value}: -None - -@item @emph{Example}: -@smallexample -program test_cpu_time - real :: start, finish - call cpu_time(start) - ! put code to test here - call cpu_time(finish) - print '("Time = ",f6.3," seconds.")',finish-start -end program test_cpu_time -@end smallexample - -@item @emph{See also}: -@ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME} -@end table - - - -@node CSHIFT -@section @code{CSHIFT} --- Circular shift elements of an array -@fnindex CSHIFT -@cindex array, shift circularly -@cindex array, permutation -@cindex array, rotate - -@table @asis -@item @emph{Description}: -@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of -@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is -taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the -range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. -If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted -by @var{SHIFT} places. If rank is greater than one, then all complete rank one -sections of @var{ARRAY} along the given dimension are shifted. Elements -shifted out one end of each rank one section are shifted back in the other end. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of any type. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@item @var{DIM} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -Returns an array of same type and rank as the @var{ARRAY} argument. - -@item @emph{Example}: -@smallexample -program test_cshift - integer, dimension(3,3) :: a - a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) - print '(3i3)', a(1,:) - print '(3i3)', a(2,:) - print '(3i3)', a(3,:) - a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) - print * - print '(3i3)', a(1,:) - print '(3i3)', a(2,:) - print '(3i3)', a(3,:) -end program test_cshift -@end smallexample -@end table - - - -@node CTIME -@section @code{CTIME} --- Convert a time into a string -@fnindex CTIME -@cindex time, conversion to string -@cindex conversion, to string - -@table @asis -@item @emph{Description}: -@code{CTIME} converts a system time value, such as returned by -@code{TIME8}, to a string. Unless the application has called -@code{setlocale}, the output will be in the default locale, of length -24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales, -a longer string may result. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL CTIME(TIME, RESULT)}. -@item @code{RESULT = CTIME(TIME)}. -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{TIME} @tab The type shall be of type @code{INTEGER}. -@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and -of default kind. It is an @code{INTENT(OUT)} argument. If the length -of this variable is too short for the time and date string to fit -completely, it will be blank on procedure return. -@end multitable - -@item @emph{Return value}: -The converted date and time as a string. - -@item @emph{Example}: -@smallexample -program test_ctime - integer(8) :: i - character(len=30) :: date - i = time8() - - ! Do something, main part of the program - - call ctime(i,date) - print *, 'Program was started on ', date -end program test_ctime -@end smallexample - -@item @emph{See Also}: -@ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} -@end table - - - -@node DATE_AND_TIME -@section @code{DATE_AND_TIME} --- Date and time subroutine -@fnindex DATE_AND_TIME -@cindex date, current -@cindex current date -@cindex time, current -@cindex current time - -@table @asis -@item @emph{Description}: -@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and -time information from the real-time system clock. @var{DATE} is -@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and -has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, -representing the difference with respect to Coordinated Universal Time (UTC). -Unavailable time and date parameters return blanks. - -@var{VALUES} is @code{INTENT(OUT)} and provides the following: - -@multitable @columnfractions .15 .30 .40 -@item @tab @code{VALUE(1)}: @tab The year -@item @tab @code{VALUE(2)}: @tab The month -@item @tab @code{VALUE(3)}: @tab The day of the month -@item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes -@item @tab @code{VALUE(5)}: @tab The hour of the day -@item @tab @code{VALUE(6)}: @tab The minutes of the hour -@item @tab @code{VALUE(7)}: @tab The seconds of the minute -@item @tab @code{VALUE(8)}: @tab The milliseconds of the second -@end multitable - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} -or larger, and of default kind. -@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} -or larger, and of default kind. -@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} -or larger, and of default kind. -@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. -@end multitable - -@item @emph{Return value}: -None - -@item @emph{Example}: -@smallexample -program test_time_and_date - character(8) :: date - character(10) :: time - character(5) :: zone - integer,dimension(8) :: values - ! using keyword arguments - call date_and_time(date,time,zone,values) - call date_and_time(DATE=date,ZONE=zone) - call date_and_time(TIME=time) - call date_and_time(VALUES=values) - print '(a,2x,a,2x,a)', date, time, zone - print '(8i5))', values -end program test_time_and_date -@end smallexample - -@item @emph{See also}: -@ref{CPU_TIME}, @ref{SYSTEM_CLOCK} -@end table - - - -@node DBLE -@section @code{DBLE} --- Double conversion function -@fnindex DBLE -@cindex conversion, to real - -@table @asis -@item @emph{Description}: -@code{DBLE(A)} Converts @var{A} to double precision real type. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = DBLE(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, -or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of type double precision real. - -@item @emph{Example}: -@smallexample -program test_dble - real :: x = 2.18 - integer :: i = 5 - complex :: z = (2.3,1.14) - print *, dble(x), dble(i), dble(z) -end program test_dble -@end smallexample - -@item @emph{See also}: -@ref{REAL} -@end table - - - -@node DCMPLX -@section @code{DCMPLX} --- Double complex conversion function -@fnindex DCMPLX -@cindex complex numbers, conversion to -@cindex conversion, to complex - -@table @asis -@item @emph{Description}: -@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is -converted to the real component. If @var{Y} is present it is converted to the -imaginary component. If @var{Y} is not present then the imaginary component is -set to 0.0. If @var{X} is complex then @var{Y} must not be present. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = DCMPLX(X [, Y])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, -or @code{COMPLEX}. -@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be -@code{INTEGER} or @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{COMPLEX(8)} - -@item @emph{Example}: -@smallexample -program test_dcmplx - integer :: i = 42 - real :: x = 3.14 - complex :: z - z = cmplx(i, x) - print *, dcmplx(i) - print *, dcmplx(x) - print *, dcmplx(z) - print *, dcmplx(x,i) -end program test_dcmplx -@end smallexample -@end table - - -@node DIGITS -@section @code{DIGITS} --- Significant binary digits function -@fnindex DIGITS -@cindex model representation, significant digits - -@table @asis -@item @emph{Description}: -@code{DIGITS(X)} returns the number of significant binary digits of the internal -model representation of @var{X}. For example, on a system using a 32-bit -floating point representation, a default real number would likely return 24. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = DIGITS(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER}. - -@item @emph{Example}: -@smallexample -program test_digits - integer :: i = 12345 - real :: x = 3.143 - real(8) :: y = 2.33 - print *, digits(i) - print *, digits(x) - print *, digits(y) -end program test_digits -@end smallexample -@end table - - - -@node DIM -@section @code{DIM} --- Positive difference -@fnindex DIM -@fnindex IDIM -@fnindex DDIM -@cindex positive difference - -@table @asis -@item @emph{Description}: -@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; -otherwise returns zero. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = DIM(X, Y)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} -@item @var{Y} @tab The type shall be the same type and kind as @var{X}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} or @code{REAL}. - -@item @emph{Example}: -@smallexample -program test_dim - integer :: i - real(8) :: x - i = dim(4, 15) - x = dim(4.345_8, 2.111_8) - print *, i - print *, x -end program test_dim -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later -@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable -@end table - - - -@node DOT_PRODUCT -@section @code{DOT_PRODUCT} --- Dot product function -@fnindex DOT_PRODUCT -@cindex dot product -@cindex vector product -@cindex product, vector - -@table @asis -@item @emph{Description}: -@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication -of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be -either numeric or logical and must be arrays of rank one and of equal size. If -the vectors are @code{INTEGER} or @code{REAL}, the result is -@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result -is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, -the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. -@item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array. -@end multitable - -@item @emph{Return value}: -If the arguments are numeric, the return value is a scalar of numeric type, -@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are -@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. - -@item @emph{Example}: -@smallexample -program test_dot_prod - integer, dimension(3) :: a, b - a = (/ 1, 2, 3 /) - b = (/ 4, 5, 6 /) - print '(3i3)', a - print * - print '(3i3)', b - print * - print *, dot_product(a,b) -end program test_dot_prod -@end smallexample -@end table - - - -@node DPROD -@section @code{DPROD} --- Double product function -@fnindex DPROD -@cindex product, double-precision - -@table @asis -@item @emph{Description}: -@code{DPROD(X,Y)} returns the product @code{X*Y}. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = DPROD(X, Y)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@item @var{Y} @tab The type shall be @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL(8)}. - -@item @emph{Example}: -@smallexample -program test_dprod - real :: x = 5.2 - real :: y = 2.3 - real(8) :: d - d = dprod(x,y) - print *, d -end program test_dprod -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later -@end multitable - -@end table - - -@node DREAL -@section @code{DREAL} --- Double real part function -@fnindex DREAL -@cindex complex numbers, real part - -@table @asis -@item @emph{Description}: -@code{DREAL(Z)} returns the real part of complex variable @var{Z}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = DREAL(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type shall be @code{COMPLEX(8)}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL(8)}. - -@item @emph{Example}: -@smallexample -program test_dreal - complex(8) :: z = (1.3_8,7.2_8) - print *, dreal(z) -end program test_dreal -@end smallexample - -@item @emph{See also}: -@ref{AIMAG} - -@end table - - - -@node DSHIFTL -@section @code{DSHIFTL} --- Combined left shift -@fnindex DSHIFTL -@cindex left shift, combined -@cindex shift, left - -@table @asis -@item @emph{Description}: -@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The -rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} -bits of @var{J}, and the remaining bits are the rightmost bits of -@var{I}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = DSHIFTL(I, J, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. -@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. -If both @var{I} and @var{J} have integer type, then they shall have -the same kind type parameter. @var{I} and @var{J} shall not both be -BOZ constants. -@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall -be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} -shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, -@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. -@end multitable - -@item @emph{Return value}: -If either @var{I} or @var{J} is a BOZ constant, it is first converted -as if by the intrinsic function @code{INT} to an integer type with the -kind type parameter of the other. - -@item @emph{See also}: -@ref{DSHIFTR} -@end table - - -@node DSHIFTR -@section @code{DSHIFTR} --- Combined right shift -@fnindex DSHIFTR -@cindex right shift, combined -@cindex shift, right - -@table @asis -@item @emph{Description}: -@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The -leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} -bits of @var{I}, and the remaining bits are the leftmost bits of -@var{J}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = DSHIFTR(I, J, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. -@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. -If both @var{I} and @var{J} have integer type, then they shall have -the same kind type parameter. @var{I} and @var{J} shall not both be -BOZ constants. -@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall -be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} -shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, -@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. -@end multitable - -@item @emph{Return value}: -If either @var{I} or @var{J} is a BOZ constant, it is first converted -as if by the intrinsic function @code{INT} to an integer type with the -kind type parameter of the other. - -@item @emph{See also}: -@ref{DSHIFTL} -@end table - - -@node DTIME -@section @code{DTIME} --- Execution time subroutine (or function) -@fnindex DTIME -@cindex time, elapsed -@cindex elapsed time - -@table @asis -@item @emph{Description}: -@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime -since the start of the process's execution in @var{TIME}. @var{VALUES} -returns the user and system components of this time in @code{VALUES(1)} and -@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + -VALUES(2)}. - -Subsequent invocations of @code{DTIME} return values accumulated since the -previous invocation. - -On some systems, the underlying timings are represented using types with -sufficiently small limits that overflows (wrap around) are possible, such as -32-bit types. Therefore, the values returned by this intrinsic might be, or -become, negative, or numerically less than previous values, during a single -run of the compiled program. - -Please note, that this implementation is thread safe if used within OpenMP -directives, i.e., its state will be consistent while called from multiple -threads. However, if @code{DTIME} is called from multiple threads, the result -is still the time since the last invocation. This may not give the intended -results. If possible, use @code{CPU_TIME} instead. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: - -@multitable @columnfractions .15 .30 .40 -@item @tab @code{VALUES(1)}: @tab User time in seconds. -@item @tab @code{VALUES(2)}: @tab System time in seconds. -@item @tab @code{TIME}: @tab Run time since start in seconds. -@end multitable - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL DTIME(VALUES, TIME)}. -@item @code{TIME = DTIME(VALUES)}, (not recommended). -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. -@item @var{TIME}@tab The type shall be @code{REAL(4)}. -@end multitable - -@item @emph{Return value}: -Elapsed time in seconds since the last invocation or since the start of program -execution if not called before. - -@item @emph{Example}: -@smallexample -program test_dtime - integer(8) :: i, j - real, dimension(2) :: tarray - real :: result - call dtime(tarray, result) - print *, result - print *, tarray(1) - print *, tarray(2) - do i=1,100000000 ! Just a delay - j = i * i - i - end do - call dtime(tarray, result) - print *, result - print *, tarray(1) - print *, tarray(2) -end program test_dtime -@end smallexample - -@item @emph{See also}: -@ref{CPU_TIME} - -@end table - - - -@node EOSHIFT -@section @code{EOSHIFT} --- End-off shift elements of an array -@fnindex EOSHIFT -@cindex array, shift - -@table @asis -@item @emph{Description}: -@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on -elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is -omitted it is taken to be @code{1}. @var{DIM} is a scalar of type -@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the -rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of -@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, -then all complete rank one sections of @var{ARRAY} along the given dimension are -shifted. Elements shifted out one end of each rank one section are dropped. If -@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} -is copied back in the other end. If @var{BOUNDARY} is not present then the -following are copied in depending on the type of @var{ARRAY}. - -@multitable @columnfractions .15 .80 -@item @emph{Array Type} @tab @emph{Boundary Value} -@item Numeric @tab 0 of the type and kind of @var{ARRAY}. -@item Logical @tab @code{.FALSE.}. -@item Character(@var{len}) @tab @var{len} blanks. -@end multitable - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab May be any type, not scalar. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. -@item @var{DIM} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -Returns an array of same type and rank as the @var{ARRAY} argument. - -@item @emph{Example}: -@smallexample -program test_eoshift - integer, dimension(3,3) :: a - a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) - print '(3i3)', a(1,:) - print '(3i3)', a(2,:) - print '(3i3)', a(3,:) - a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) - print * - print '(3i3)', a(1,:) - print '(3i3)', a(2,:) - print '(3i3)', a(3,:) -end program test_eoshift -@end smallexample -@end table - - - -@node EPSILON -@section @code{EPSILON} --- Epsilon function -@fnindex EPSILON -@cindex model representation, epsilon - -@table @asis -@item @emph{Description}: -@code{EPSILON(X)} returns the smallest number @var{E} of the same kind -as @var{X} such that @math{1 + E > 1}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = EPSILON(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of same type as the argument. - -@item @emph{Example}: -@smallexample -program test_epsilon - real :: x = 3.143 - real(8) :: y = 2.33 - print *, EPSILON(x) - print *, EPSILON(y) -end program test_epsilon -@end smallexample -@end table - - - -@node ERF -@section @code{ERF} --- Error function -@fnindex ERF -@cindex error function - -@table @asis -@item @emph{Description}: -@code{ERF(X)} computes the error function of @var{X}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ERF(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL}, of the same kind as -@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. - -@item @emph{Example}: -@smallexample -program test_erf - real(8) :: x = 0.17_8 - x = erf(x) -end program test_erf -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable -@end table - - - -@node ERFC -@section @code{ERFC} --- Error function -@fnindex ERFC -@cindex error function, complementary - -@table @asis -@item @emph{Description}: -@code{ERFC(X)} computes the complementary error function of @var{X}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ERFC(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} and of the same kind as @var{X}. -It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. - -@item @emph{Example}: -@smallexample -program test_erfc - real(8) :: x = 0.17_8 - x = erfc(x) -end program test_erfc -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable -@end table - - - -@node ERFC_SCALED -@section @code{ERFC_SCALED} --- Error function -@fnindex ERFC_SCALED -@cindex error function, complementary, exponentially-scaled - -@table @asis -@item @emph{Description}: -@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary -error function of @var{X}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ERFC_SCALED(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} and of the same kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_erfc_scaled - real(8) :: x = 0.17_8 - x = erfc_scaled(x) -end program test_erfc_scaled -@end smallexample -@end table - - - -@node ETIME -@section @code{ETIME} --- Execution time subroutine (or function) -@fnindex ETIME -@cindex time, elapsed - -@table @asis -@item @emph{Description}: -@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime -since the start of the process's execution in @var{TIME}. @var{VALUES} -returns the user and system components of this time in @code{VALUES(1)} and -@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. - -On some systems, the underlying timings are represented using types with -sufficiently small limits that overflows (wrap around) are possible, such as -32-bit types. Therefore, the values returned by this intrinsic might be, or -become, negative, or numerically less than previous values, during a single -run of the compiled program. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: - -@multitable @columnfractions .15 .30 .60 -@item @tab @code{VALUES(1)}: @tab User time in seconds. -@item @tab @code{VALUES(2)}: @tab System time in seconds. -@item @tab @code{TIME}: @tab Run time since start in seconds. -@end multitable - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL ETIME(VALUES, TIME)}. -@item @code{TIME = ETIME(VALUES)}, (not recommended). -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. -@item @var{TIME}@tab The type shall be @code{REAL(4)}. -@end multitable - -@item @emph{Return value}: -Elapsed time in seconds since the start of program execution. - -@item @emph{Example}: -@smallexample -program test_etime - integer(8) :: i, j - real, dimension(2) :: tarray - real :: result - call ETIME(tarray, result) - print *, result - print *, tarray(1) - print *, tarray(2) - do i=1,100000000 ! Just a delay - j = i * i - i - end do - call ETIME(tarray, result) - print *, result - print *, tarray(1) - print *, tarray(2) -end program test_etime -@end smallexample - -@item @emph{See also}: -@ref{CPU_TIME} - -@end table - - - -@node EXECUTE_COMMAND_LINE -@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command -@fnindex EXECUTE_COMMAND_LINE -@cindex system, system call -@cindex command line - -@table @asis -@item @emph{Description}: -@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or -asynchronously. - -The @code{COMMAND} argument is passed to the shell and executed, using -the C library's @code{system} call. (The shell is @code{sh} on Unix -systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present -and has the value false, the execution of the command is asynchronous -if the system supports it; otherwise, the command is executed -synchronously. - -The three last arguments allow the user to get status information. After -synchronous execution, @code{EXITSTAT} contains the integer exit code of -the command, as returned by @code{system}. @code{CMDSTAT} is set to zero -if the command line was executed (whatever its exit status was). -@code{CMDMSG} is assigned an error message if an error has occurred. - -Note that the @code{system} function need not be thread-safe. It is -the responsibility of the user to ensure that @code{system} is not -called concurrently. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. -@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. -@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the -default kind. -@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the -default kind. -@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the -default kind. -@end multitable - -@item @emph{Example}: -@smallexample -program test_exec - integer :: i - - call execute_command_line ("external_prog.exe", exitstat=i) - print *, "Exit status of external_prog.exe was ", i - - call execute_command_line ("reindex_files.exe", wait=.false.) - print *, "Now reindexing files in the background" - -end program test_exec -@end smallexample - - -@item @emph{Note}: - -Because this intrinsic is implemented in terms of the @code{system} -function call, its behavior with respect to signaling is processor -dependent. In particular, on POSIX-compliant systems, the SIGINT and -SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As -such, if the parent process is terminated, the child process might not be -terminated alongside. - - -@item @emph{See also}: -@ref{SYSTEM} -@end table - - - -@node EXIT -@section @code{EXIT} --- Exit the program with status. -@fnindex EXIT -@cindex program termination -@cindex terminate program - -@table @asis -@item @emph{Description}: -@code{EXIT} causes immediate termination of the program with status. If status -is omitted it returns the canonical @emph{success} for the system. All Fortran -I/O units are closed. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL EXIT([STATUS])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. -@end multitable - -@item @emph{Return value}: -@code{STATUS} is passed to the parent process on exit. - -@item @emph{Example}: -@smallexample -program test_exit - integer :: STATUS = 0 - print *, 'This program is going to exit.' - call EXIT(STATUS) -end program test_exit -@end smallexample - -@item @emph{See also}: -@ref{ABORT}, @ref{KILL} -@end table - - - -@node EXP -@section @code{EXP} --- Exponential function -@fnindex EXP -@fnindex DEXP -@fnindex CEXP -@fnindex ZEXP -@fnindex CDEXP -@cindex exponential function -@cindex logarithm function, inverse - -@table @asis -@item @emph{Description}: -@code{EXP(X)} computes the base @math{e} exponential of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later, has overloads that are GNU extensions - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = EXP(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or -@code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has same type and kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_exp - real :: x = 1.0 - x = exp(x) -end program test_exp -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later -@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later -@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension -@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension -@end multitable -@end table - - - -@node EXPONENT -@section @code{EXPONENT} --- Exponent function -@fnindex EXPONENT -@cindex real number, exponent -@cindex floating point, exponent - -@table @asis -@item @emph{Description}: -@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} -is zero the value returned is zero. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = EXPONENT(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type default @code{INTEGER}. - -@item @emph{Example}: -@smallexample -program test_exponent - real :: x = 1.0 - integer :: i - i = exponent(x) - print *, i - print *, exponent(0.0) -end program test_exponent -@end smallexample -@end table - - - -@node EXTENDS_TYPE_OF -@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension -@fnindex EXTENDS_TYPE_OF - -@table @asis -@item @emph{Description}: -Query dynamic type for extension. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be an object of extensible declared type or -unlimited polymorphic. -@item @var{MOLD} @tab Shall be an object of extensible declared type or -unlimited polymorphic. -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type default logical. It is true if and only if -the dynamic type of A is an extension type of the dynamic type of MOLD. - - -@item @emph{See also}: -@ref{SAME_TYPE_AS} -@end table - - - -@node FDATE -@section @code{FDATE} --- Get the current time as a string -@fnindex FDATE -@cindex time, current -@cindex current time -@cindex date, current -@cindex current date - -@table @asis -@item @emph{Description}: -@code{FDATE(DATE)} returns the current date (using the same format as -@code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, -TIME())}. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL FDATE(DATE)}. -@item @code{DATE = FDATE()}. -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the -default kind. It is an @code{INTENT(OUT)} argument. If the length of -this variable is too short for the date and time string to fit -completely, it will be blank on procedure return. -@end multitable - -@item @emph{Return value}: -The current date and time as a string. - -@item @emph{Example}: -@smallexample -program test_fdate - integer(8) :: i, j - character(len=30) :: date - call fdate(date) - print *, 'Program started on ', date - do i = 1, 100000000 ! Just a delay - j = i * i - i - end do - call fdate(date) - print *, 'Program ended on ', date -end program test_fdate -@end smallexample - -@item @emph{See also}: -@ref{DATE_AND_TIME}, @ref{CTIME} -@end table - - -@node FGET -@section @code{FGET} --- Read a single character in stream mode from stdin -@fnindex FGET -@cindex read character, stream mode -@cindex stream mode, read character -@cindex file operation, read character - -@table @asis -@item @emph{Description}: -Read a single character in stream mode from stdin by bypassing normal -formatted output. Stream I/O should not be mixed with normal record-oriented -(formatted or unformatted) I/O on the same unit; the results are unpredictable. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -Note that the @code{FGET} intrinsic is provided for backwards compatibility with -@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. -Programmers should consider the use of new stream IO feature in new code -for future portability. See also @ref{Fortran 2003 status}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL FGET(C [, STATUS])} -@item @code{STATUS = FGET(C)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab The type shall be @code{CHARACTER} and of default -kind. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. -Returns 0 on success, -1 on end-of-file, and a system specific positive -error code otherwise. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_fget - INTEGER, PARAMETER :: strlen = 100 - INTEGER :: status, i = 1 - CHARACTER(len=strlen) :: str = "" - - WRITE (*,*) 'Enter text:' - DO - CALL fget(str(i:i), status) - if (status /= 0 .OR. i > strlen) exit - i = i + 1 - END DO - WRITE (*,*) TRIM(str) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{FGETC}, @ref{FPUT}, @ref{FPUTC} -@end table - - - -@node FGETC -@section @code{FGETC} --- Read a single character in stream mode -@fnindex FGETC -@cindex read character, stream mode -@cindex stream mode, read character -@cindex file operation, read character - -@table @asis -@item @emph{Description}: -Read a single character in stream mode by bypassing normal formatted output. -Stream I/O should not be mixed with normal record-oriented (formatted or -unformatted) I/O on the same unit; the results are unpredictable. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -Note that the @code{FGET} intrinsic is provided for backwards compatibility -with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. -Programmers should consider the use of new stream IO feature in new code -for future portability. See also @ref{Fortran 2003 status}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL FGETC(UNIT, C [, STATUS])} -@item @code{STATUS = FGETC(UNIT, C)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab The type shall be @code{INTEGER}. -@item @var{C} @tab The type shall be @code{CHARACTER} and of default -kind. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. -Returns 0 on success, -1 on end-of-file and a system specific positive -error code otherwise. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_fgetc - INTEGER :: fd = 42, status - CHARACTER :: c - - OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") - DO - CALL fgetc(fd, c, status) - IF (status /= 0) EXIT - call fput(c) - END DO - CLOSE(UNIT=fd) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{FGET}, @ref{FPUT}, @ref{FPUTC} -@end table - - - -@node FLOOR -@section @code{FLOOR} --- Integer floor function -@fnindex FLOOR -@cindex floor -@cindex rounding, floor - -@table @asis -@item @emph{Description}: -@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = FLOOR(A [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type shall be @code{REAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present -and of default-kind @code{INTEGER} otherwise. - -@item @emph{Example}: -@smallexample -program test_floor - real :: x = 63.29 - real :: y = -63.59 - print *, floor(x) ! returns 63 - print *, floor(y) ! returns -64 -end program test_floor -@end smallexample - -@item @emph{See also}: -@ref{CEILING}, @ref{NINT} - -@end table - - - -@node FLUSH -@section @code{FLUSH} --- Flush I/O unit(s) -@fnindex FLUSH -@cindex file operation, flush - -@table @asis -@item @emph{Description}: -Flushes Fortran unit(s) currently open for output. Without the optional -argument, all units are flushed, otherwise just the unit specified. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL FLUSH(UNIT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Note}: -Beginning with the Fortran 2003 standard, there is a @code{FLUSH} -statement that should be preferred over the @code{FLUSH} intrinsic. - -The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement -have identical effect: they flush the runtime library's I/O buffer so -that the data becomes visible to other processes. This does not guarantee -that the data is committed to disk. - -On POSIX systems, you can request that all data is transferred to the -storage device by calling the @code{fsync} function, with the POSIX file -descriptor of the I/O unit as argument (retrieved with GNU intrinsic -@code{FNUM}). The following example shows how: - -@smallexample - ! Declare the interface for POSIX fsync function - interface - function fsync (fd) bind(c,name="fsync") - use iso_c_binding, only: c_int - integer(c_int), value :: fd - integer(c_int) :: fsync - end function fsync - end interface - - ! Variable declaration - integer :: ret - - ! Opening unit 10 - open (10,file="foo") - - ! ... - ! Perform I/O on unit 10 - ! ... - - ! Flush and sync - flush(10) - ret = fsync(fnum(10)) - - ! Handle possible error - if (ret /= 0) stop "Error calling FSYNC" -@end smallexample - -@end table - - - -@node FNUM -@section @code{FNUM} --- File number function -@fnindex FNUM -@cindex file operation, file number - -@table @asis -@item @emph{Description}: -@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the -open Fortran I/O unit @code{UNIT}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = FNUM(UNIT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} - -@item @emph{Example}: -@smallexample -program test_fnum - integer :: i - open (unit=10, status = "scratch") - i = fnum(10) - print *, i - close (10) -end program test_fnum -@end smallexample -@end table - - - -@node FPUT -@section @code{FPUT} --- Write a single character in stream mode to stdout -@fnindex FPUT -@cindex write character, stream mode -@cindex stream mode, write character -@cindex file operation, write character - -@table @asis -@item @emph{Description}: -Write a single character in stream mode to stdout by bypassing normal -formatted output. Stream I/O should not be mixed with normal record-oriented -(formatted or unformatted) I/O on the same unit; the results are unpredictable. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -Note that the @code{FGET} intrinsic is provided for backwards compatibility with -@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. -Programmers should consider the use of new stream IO feature in new code -for future portability. See also @ref{Fortran 2003 status}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL FPUT(C [, STATUS])} -@item @code{STATUS = FPUT(C)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab The type shall be @code{CHARACTER} and of default -kind. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. -Returns 0 on success, -1 on end-of-file and a system specific positive -error code otherwise. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_fput - CHARACTER(len=10) :: str = "gfortran" - INTEGER :: i - DO i = 1, len_trim(str) - CALL fput(str(i:i)) - END DO -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{FPUTC}, @ref{FGET}, @ref{FGETC} -@end table - - - -@node FPUTC -@section @code{FPUTC} --- Write a single character in stream mode -@fnindex FPUTC -@cindex write character, stream mode -@cindex stream mode, write character -@cindex file operation, write character - -@table @asis -@item @emph{Description}: -Write a single character in stream mode by bypassing normal formatted -output. Stream I/O should not be mixed with normal record-oriented -(formatted or unformatted) I/O on the same unit; the results are unpredictable. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -Note that the @code{FGET} intrinsic is provided for backwards compatibility with -@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. -Programmers should consider the use of new stream IO feature in new code -for future portability. See also @ref{Fortran 2003 status}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL FPUTC(UNIT, C [, STATUS])} -@item @code{STATUS = FPUTC(UNIT, C)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab The type shall be @code{INTEGER}. -@item @var{C} @tab The type shall be @code{CHARACTER} and of default -kind. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. -Returns 0 on success, -1 on end-of-file and a system specific positive -error code otherwise. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_fputc - CHARACTER(len=10) :: str = "gfortran" - INTEGER :: fd = 42, i - - OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") - DO i = 1, len_trim(str) - CALL fputc(fd, str(i:i)) - END DO - CLOSE(fd) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{FPUT}, @ref{FGET}, @ref{FGETC} -@end table - - - -@node FRACTION -@section @code{FRACTION} --- Fractional part of the model representation -@fnindex FRACTION -@cindex real number, fraction -@cindex floating point, fraction - -@table @asis -@item @emph{Description}: -@code{FRACTION(X)} returns the fractional part of the model -representation of @code{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{Y = FRACTION(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type of the argument shall be a @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as the argument. -The fractional part of the model representation of @code{X} is returned; -it is @code{X * RADIX(X)**(-EXPONENT(X))}. - -@item @emph{Example}: -@smallexample -program test_fraction - real :: x - x = 178.1387e-4 - print *, fraction(x), x * radix(x)**(-exponent(x)) -end program test_fraction -@end smallexample - -@end table - - - -@node FREE -@section @code{FREE} --- Frees memory -@fnindex FREE -@cindex pointer, cray - -@table @asis -@item @emph{Description}: -Frees memory previously allocated by @code{MALLOC}. The @code{FREE} -intrinsic is an extension intended to be used with Cray pointers, and is -provided in GNU Fortran to allow user to compile legacy code. For -new code using Fortran 95 pointers, the memory de-allocation intrinsic is -@code{DEALLOCATE}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL FREE(PTR)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the -location of the memory that should be de-allocated. -@end multitable - -@item @emph{Return value}: -None - -@item @emph{Example}: -See @code{MALLOC} for an example. - -@item @emph{See also}: -@ref{MALLOC} -@end table - - - -@node FSEEK -@section @code{FSEEK} --- Low level file positioning subroutine -@fnindex FSEEK -@cindex file operation, seek -@cindex file operation, position - -@table @asis -@item @emph{Description}: -Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} -is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, -if set to 1, @var{OFFSET} is taken to be relative to the current position -@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. -On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek -fails silently. - -This intrinsic routine is not fully backwards compatible with @command{g77}. -In @command{g77}, the @code{FSEEK} takes a statement label instead of a -@var{STATUS} variable. If FSEEK is used in old code, change -@smallexample - CALL FSEEK(UNIT, OFFSET, WHENCE, *label) -@end smallexample -to -@smallexample - INTEGER :: status - CALL FSEEK(UNIT, OFFSET, WHENCE, status) - IF (status /= 0) GOTO label -@end smallexample - -Please note that GNU Fortran provides the Fortran 2003 Stream facility. -Programmers should consider the use of new stream IO feature in new code -for future portability. See also @ref{Fortran 2003 status}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. -@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. -@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. -Its value shall be either 0, 1 or 2. -@item @var{STATUS} @tab (Optional) shall be a scalar of type -@code{INTEGER(4)}. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_fseek - INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 - INTEGER :: fd, offset, ierr - - ierr = 0 - offset = 5 - fd = 10 - - OPEN(UNIT=fd, FILE="fseek.test") - CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET - print *, FTELL(fd), ierr - - CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end - print *, FTELL(fd), ierr - - CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning - print *, FTELL(fd), ierr - - CLOSE(UNIT=fd) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{FTELL} -@end table - - - -@node FSTAT -@section @code{FSTAT} --- Get file status -@fnindex FSTAT -@cindex file system, file status - -@table @asis -@item @emph{Description}: -@code{FSTAT} is identical to @ref{STAT}, except that information about an -already opened file is obtained. - -The elements in @code{VALUES} are the same as described by @ref{STAT}. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} -@item @code{STATUS = FSTAT(UNIT, VALUES)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. -@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 -on success and a system specific error code otherwise. -@end multitable - -@item @emph{Example}: -See @ref{STAT} for an example. - -@item @emph{See also}: -To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT} -@end table - - - -@node FTELL -@section @code{FTELL} --- Current stream position -@fnindex FTELL -@cindex file operation, position - -@table @asis -@item @emph{Description}: -Retrieves the current position within an open file. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL FTELL(UNIT, OFFSET)} -@item @code{OFFSET = FTELL(UNIT)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{OFFSET} @tab Shall of type @code{INTEGER}. -@item @var{UNIT} @tab Shall of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -In either syntax, @var{OFFSET} is set to the current offset of unit -number @var{UNIT}, or to @math{-1} if the unit is not currently open. - -@item @emph{Example}: -@smallexample -PROGRAM test_ftell - INTEGER :: i - OPEN(10, FILE="temp.dat") - CALL ftell(10,i) - WRITE(*,*) i -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{FSEEK} -@end table - - - -@node GAMMA -@section @code{GAMMA} --- Gamma function -@fnindex GAMMA -@fnindex DGAMMA -@cindex Gamma function -@cindex Factorial function - -@table @asis -@item @emph{Description}: -@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, -integer values of @var{X} the Gamma function simplifies to the factorial -function @math{\Gamma(x)=(x-1)!}. - -@tex -$$ -\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t -$$ -@end tex - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{X = GAMMA(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL} and neither zero -nor a negative integer. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} of the same kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_gamma - real :: x = 1.0 - x = gamma(x) ! returns 1.0 -end program test_gamma -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension -@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension -@end multitable - -@item @emph{See also}: -Logarithm of the Gamma function: @ref{LOG_GAMMA} - -@end table - - - -@node GERROR -@section @code{GERROR} --- Get last system error message -@fnindex GERROR -@cindex system, error handling - -@table @asis -@item @emph{Description}: -Returns the system error message corresponding to the last system error. -This resembles the functionality of @code{strerror(3)} in C. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GERROR(RESULT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_gerror - CHARACTER(len=100) :: msg - CALL gerror(msg) - WRITE(*,*) msg -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{IERRNO}, @ref{PERROR} -@end table - - - -@node GETARG -@section @code{GETARG} --- Get command line arguments -@fnindex GETARG -@cindex command-line arguments -@cindex arguments, to program - -@table @asis -@item @emph{Description}: -Retrieve the @var{POS}-th argument that was passed on the -command line when the containing program was invoked. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. In new code, programmers should consider the use of -the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 -standard. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GETARG(POS, VALUE)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than -the default integer kind; @math{@var{POS} \geq 0} -@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default -kind. -@item @var{VALUE} @tab Shall be of type @code{CHARACTER}. -@end multitable - -@item @emph{Return value}: -After @code{GETARG} returns, the @var{VALUE} argument holds the -@var{POS}th command line argument. If @var{VALUE} can not hold the -argument, it is truncated to fit the length of @var{VALUE}. If there are -less than @var{POS} arguments specified at the command line, @var{VALUE} -will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set -to the name of the program (on systems that support this feature). - -@item @emph{Example}: -@smallexample -PROGRAM test_getarg - INTEGER :: i - CHARACTER(len=32) :: arg - - DO i = 1, iargc() - CALL getarg(i, arg) - WRITE (*,*) arg - END DO -END PROGRAM -@end smallexample - -@item @emph{See also}: -GNU Fortran 77 compatibility function: @ref{IARGC} - -Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, -@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} -@end table - - - -@node GET_COMMAND -@section @code{GET_COMMAND} --- Get the entire command line -@fnindex GET_COMMAND -@cindex command-line arguments -@cindex arguments, to program - -@table @asis -@item @emph{Description}: -Retrieve the entire command line that was used to invoke the program. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and -of default kind. -@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of -default kind. -@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of -default kind. -@end multitable - -@item @emph{Return value}: -If @var{COMMAND} is present, stores the entire command line that was used -to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is -assigned the length of the command line. If @var{STATUS} is present, it -is assigned 0 upon success of the command, -1 if @var{COMMAND} is too -short to store the command line, or a positive value in case of an error. - -@item @emph{Example}: -@smallexample -PROGRAM test_get_command - CHARACTER(len=255) :: cmd - CALL get_command(cmd) - WRITE (*,*) TRIM(cmd) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} -@end table - - - -@node GET_COMMAND_ARGUMENT -@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments -@fnindex GET_COMMAND_ARGUMENT -@cindex command-line arguments -@cindex arguments, to program - -@table @asis -@item @emph{Description}: -Retrieve the @var{NUMBER}-th argument that was passed on the -command line when the containing program was invoked. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of -default kind, @math{@var{NUMBER} \geq 0} -@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} -and of default kind. -@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} -and of default kind. -@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} -and of default kind. -@end multitable - -@item @emph{Return value}: -After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the -@var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is -truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} -arguments specified at the command line, @var{VALUE} will be filled with blanks. -If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on -systems that support this feature). The @var{LENGTH} argument contains the -length of the @var{NUMBER}-th command line argument. If the argument retrieval -fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated -command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is -zero. - -@item @emph{Example}: -@smallexample -PROGRAM test_get_command_argument - INTEGER :: i - CHARACTER(len=32) :: arg - - i = 0 - DO - CALL get_command_argument(i, arg) - IF (LEN_TRIM(arg) == 0) EXIT - - WRITE (*,*) TRIM(arg) - i = i+1 - END DO -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT} -@end table - - - -@node GETCWD -@section @code{GETCWD} --- Get current working directory -@fnindex GETCWD -@cindex system, working directory - -@table @asis -@item @emph{Description}: -Get current working directory. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL GETCWD(C [, STATUS])} -@item @code{STATUS = GETCWD(C)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. -@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, -a system specific and nonzero error code otherwise. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_getcwd - CHARACTER(len=255) :: cwd - CALL getcwd(cwd) - WRITE(*,*) TRIM(cwd) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{CHDIR} -@end table - - - -@node GETENV -@section @code{GETENV} --- Get an environmental variable -@fnindex GETENV -@cindex environment variable - -@table @asis -@item @emph{Description}: -Get the @var{VALUE} of the environmental variable @var{NAME}. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. In new code, programmers should consider the use of -the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran -2003 standard. - -Note that @code{GETENV} need not be thread-safe. It is the -responsibility of the user to ensure that the environment is not being -updated concurrently with a call to the @code{GETENV} intrinsic. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GETENV(NAME, VALUE)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. -@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. -@end multitable - -@item @emph{Return value}: -Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is -not large enough to hold the data, it is truncated. If @var{NAME} -is not set, @var{VALUE} will be filled with blanks. - -@item @emph{Example}: -@smallexample -PROGRAM test_getenv - CHARACTER(len=255) :: homedir - CALL getenv("HOME", homedir) - WRITE (*,*) TRIM(homedir) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{GET_ENVIRONMENT_VARIABLE} -@end table - - - -@node GET_ENVIRONMENT_VARIABLE -@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable -@fnindex GET_ENVIRONMENT_VARIABLE -@cindex environment variable - -@table @asis -@item @emph{Description}: -Get the @var{VALUE} of the environmental variable @var{NAME}. - -Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It -is the responsibility of the user to ensure that the environment is -not being updated concurrently with a call to the -@code{GET_ENVIRONMENT_VARIABLE} intrinsic. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} -and of default kind. -@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} -and of default kind. -@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} -and of default kind. -@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} -and of default kind. -@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} -and of default kind. -@end multitable - -@item @emph{Return value}: -Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is -not large enough to hold the data, it is truncated. If @var{NAME} -is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} -contains the length needed for storing the environment variable @var{NAME} -or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present -but too short for the environment variable; it is 1 if the environment -variable does not exist and 2 if the processor does not support environment -variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is -present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} -are significant; otherwise they are not part of the environment variable -name. - -@item @emph{Example}: -@smallexample -PROGRAM test_getenv - CHARACTER(len=255) :: homedir - CALL get_environment_variable("HOME", homedir) - WRITE (*,*) TRIM(homedir) -END PROGRAM -@end smallexample -@end table - - - -@node GETGID -@section @code{GETGID} --- Group ID function -@fnindex GETGID -@cindex system, group ID - -@table @asis -@item @emph{Description}: -Returns the numerical group ID of the current process. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = GETGID()} - -@item @emph{Return value}: -The return value of @code{GETGID} is an @code{INTEGER} of the default -kind. - - -@item @emph{Example}: -See @code{GETPID} for an example. - -@item @emph{See also}: -@ref{GETPID}, @ref{GETUID} -@end table - - - -@node GETLOG -@section @code{GETLOG} --- Get login name -@fnindex GETLOG -@cindex system, login name -@cindex login name - -@table @asis -@item @emph{Description}: -Gets the username under which the program is running. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GETLOG(C)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. -@end multitable - -@item @emph{Return value}: -Stores the current user name in @var{LOGIN}. (On systems where POSIX -functions @code{geteuid} and @code{getpwuid} are not available, and -the @code{getlogin} function is not implemented either, this will -return a blank string.) - -@item @emph{Example}: -@smallexample -PROGRAM TEST_GETLOG - CHARACTER(32) :: login - CALL GETLOG(login) - WRITE(*,*) login -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{GETUID} -@end table - - - -@node GETPID -@section @code{GETPID} --- Process ID function -@fnindex GETPID -@cindex system, process ID -@cindex process ID - -@table @asis -@item @emph{Description}: -Returns the numerical process identifier of the current process. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = GETPID()} - -@item @emph{Return value}: -The return value of @code{GETPID} is an @code{INTEGER} of the default -kind. - - -@item @emph{Example}: -@smallexample -program info - print *, "The current process ID is ", getpid() - print *, "Your numerical user ID is ", getuid() - print *, "Your numerical group ID is ", getgid() -end program info -@end smallexample - -@item @emph{See also}: -@ref{GETGID}, @ref{GETUID} -@end table - - - -@node GETUID -@section @code{GETUID} --- User ID function -@fnindex GETUID -@cindex system, user ID -@cindex user id - -@table @asis -@item @emph{Description}: -Returns the numerical user ID of the current process. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = GETUID()} - -@item @emph{Return value}: -The return value of @code{GETUID} is an @code{INTEGER} of the default -kind. - - -@item @emph{Example}: -See @code{GETPID} for an example. - -@item @emph{See also}: -@ref{GETPID}, @ref{GETLOG} -@end table - - - -@node GMTIME -@section @code{GMTIME} --- Convert time to GMT info -@fnindex GMTIME -@cindex time, conversion to GMT info - -@table @asis -@item @emph{Description}: -Given a system time value @var{TIME} (as provided by the @code{TIME8} -intrinsic), fills @var{VALUES} with values extracted from it appropriate -to the UTC time zone (Universal Coordinated Time, also known in some -countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL GMTIME(TIME, VALUES)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{TIME} @tab An @code{INTEGER} scalar expression -corresponding to a system time, with @code{INTENT(IN)}. -@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, -with @code{INTENT(OUT)}. -@end multitable - -@item @emph{Return value}: -The elements of @var{VALUES} are assigned as follows: -@enumerate -@item Seconds after the minute, range 0--59 or 0--61 to allow for leap -seconds -@item Minutes after the hour, range 0--59 -@item Hours past midnight, range 0--23 -@item Day of month, range 0--31 -@item Number of months since January, range 0--12 -@item Years since 1900 -@item Number of days since Sunday, range 0--6 -@item Days since January 1 -@item Daylight savings indicator: positive if daylight savings is in -effect, zero if not, and negative if the information is not available. -@end enumerate - -@item @emph{See also}: -@ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} - -@end table - - - -@node HOSTNM -@section @code{HOSTNM} --- Get system host name -@fnindex HOSTNM -@cindex system, host name - -@table @asis -@item @emph{Description}: -Retrieves the host name of the system on which the program is running. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL HOSTNM(C [, STATUS])} -@item @code{STATUS = HOSTNM(NAME)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. -Returns 0 on success, or a system specific error code otherwise. -@end multitable - -@item @emph{Return value}: -In either syntax, @var{NAME} is set to the current hostname if it can -be obtained, or to a blank string otherwise. - -@end table - - - -@node HUGE -@section @code{HUGE} --- Largest number of a kind -@fnindex HUGE -@cindex limits, largest number -@cindex model representation, largest number - -@table @asis -@item @emph{Description}: -@code{HUGE(X)} returns the largest number that is not an infinity in -the model of the type of @code{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = HUGE(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X} - -@item @emph{Example}: -@smallexample -program test_huge_tiny - print *, huge(0), huge(0.0), huge(0.0d0) - print *, tiny(0.0), tiny(0.0d0) -end program test_huge_tiny -@end smallexample -@end table - - - -@node HYPOT -@section @code{HYPOT} --- Euclidean distance function -@fnindex HYPOT -@cindex Euclidean distance - -@table @asis -@item @emph{Description}: -@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to -@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = HYPOT(X, Y)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@item @var{Y} @tab The type and kind type parameter shall be the same as -@var{X}. -@end multitable - -@item @emph{Return value}: -The return value has the same type and kind type parameter as @var{X}. - -@item @emph{Example}: -@smallexample -program test_hypot - real(4) :: x = 1.e0_4, y = 0.5e0_4 - x = hypot(x,y) -end program test_hypot -@end smallexample -@end table - - - -@node IACHAR -@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence -@fnindex IACHAR -@cindex @acronym{ASCII} collating sequence -@cindex collating sequence, @acronym{ASCII} -@cindex conversion, to integer - -@table @asis -@item @emph{Description}: -@code{IACHAR(C)} returns the code for the @acronym{ASCII} character -in the first character position of @code{C}. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IACHAR(C [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - -@item @emph{Example}: -@smallexample -program test_iachar - integer i - i = iachar(' ') -end program test_iachar -@end smallexample - -@item @emph{Note}: -See @ref{ICHAR} for a discussion of converting between numerical values -and formatted string representations. - -@item @emph{See also}: -@ref{ACHAR}, @ref{CHAR}, @ref{ICHAR} - -@end table - - - -@node IALL -@section @code{IALL} --- Bitwise AND of array elements -@fnindex IALL -@cindex array, AND -@cindex bits, AND of array elements - -@table @asis -@item @emph{Description}: -Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} -if the corresponding element in @var{MASK} is @code{TRUE}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = IALL(ARRAY[, MASK])} -@item @code{RESULT = IALL(ARRAY, DIM[, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} -@item @var{DIM} @tab (Optional) shall be a scalar of type -@code{INTEGER} with a value in the range from 1 to n, where n -equals the rank of @var{ARRAY}. -@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} -and either be a scalar or an array of the same shape as @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as @var{ARRAY}. - -If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in -@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals -the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with -dimension @var{DIM} dropped is returned. - -@item @emph{Example}: -@smallexample -PROGRAM test_iall - INTEGER(1) :: a(2) - - a(1) = b'00100100' - a(2) = b'01101010' - - ! prints 00100000 - PRINT '(b8.8)', IALL(a) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{IANY}, @ref{IPARITY}, @ref{IAND} -@end table - - - -@node IAND -@section @code{IAND} --- Bitwise logical and -@fnindex IAND -@cindex bitwise logical and -@cindex logical and, bitwise - -@table @asis -@item @emph{Description}: -Bitwise logical @code{AND}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IAND(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{J} @tab The type shall be @code{INTEGER}, of the same -kind as @var{I}. (As a GNU extension, different kinds are also -permitted.) -@end multitable - -@item @emph{Return value}: -The return type is @code{INTEGER}, of the same kind as the -arguments. (If the argument kinds differ, it is of the same kind as -the larger argument.) - -@item @emph{Example}: -@smallexample -PROGRAM test_iand - INTEGER :: a, b - DATA a / Z'F' /, b / Z'3' / - WRITE (*,*) IAND(a, b) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} - -@end table - - - -@node IANY -@section @code{IANY} --- Bitwise OR of array elements -@fnindex IANY -@cindex array, OR -@cindex bits, OR of array elements - -@table @asis -@item @emph{Description}: -Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along -dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = IANY(ARRAY[, MASK])} -@item @code{RESULT = IANY(ARRAY, DIM[, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} -@item @var{DIM} @tab (Optional) shall be a scalar of type -@code{INTEGER} with a value in the range from 1 to n, where n -equals the rank of @var{ARRAY}. -@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} -and either be a scalar or an array of the same shape as @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as @var{ARRAY}. - -If @var{DIM} is absent, a scalar with the bitwise OR of all elements in -@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals -the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with -dimension @var{DIM} dropped is returned. - -@item @emph{Example}: -@smallexample -PROGRAM test_iany - INTEGER(1) :: a(2) - - a(1) = b'00100100' - a(2) = b'01101010' - - ! prints 01101110 - PRINT '(b8.8)', IANY(a) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{IPARITY}, @ref{IALL}, @ref{IOR} -@end table - - - -@node IARGC -@section @code{IARGC} --- Get the number of command line arguments -@fnindex IARGC -@cindex command-line arguments -@cindex command-line arguments, number of -@cindex arguments, to program - -@table @asis -@item @emph{Description}: -@code{IARGC} returns the number of arguments passed on the -command line when the containing program was invoked. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. In new code, programmers should consider the use of -the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 -standard. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = IARGC()} - -@item @emph{Arguments}: -None. - -@item @emph{Return value}: -The number of command line arguments, type @code{INTEGER(4)}. - -@item @emph{Example}: -See @ref{GETARG} - -@item @emph{See also}: -GNU Fortran 77 compatibility subroutine: @ref{GETARG} - -Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, -@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} -@end table - - - -@node IBCLR -@section @code{IBCLR} --- Clear bit -@fnindex IBCLR -@cindex bits, unset -@cindex bits, clear - -@table @asis -@item @emph{Description}: -@code{IBCLR} returns the value of @var{I} with the bit at position -@var{POS} set to zero. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IBCLR(I, POS)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{POS} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} - -@end table - - - -@node IBITS -@section @code{IBITS} --- Bit extraction -@fnindex IBITS -@cindex bits, get -@cindex bits, extract - -@table @asis -@item @emph{Description}: -@code{IBITS} extracts a field of length @var{LEN} from @var{I}, -starting from bit position @var{POS} and extending left for @var{LEN} -bits. The result is right-justified and the remaining bits are -zeroed. The value of @code{POS+LEN} must be less than or equal to the -value @code{BIT_SIZE(I)}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IBITS(I, POS, LEN)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{POS} @tab The type shall be @code{INTEGER}. -@item @var{LEN} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR} -@end table - - - -@node IBSET -@section @code{IBSET} --- Set bit -@fnindex IBSET -@cindex bits, set - -@table @asis -@item @emph{Description}: -@code{IBSET} returns the value of @var{I} with the bit at position -@var{POS} set to one. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IBSET(I, POS)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{POS} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} - -@end table - - - -@node ICHAR -@section @code{ICHAR} --- Character-to-integer conversion function -@fnindex ICHAR -@cindex conversion, to integer - -@table @asis -@item @emph{Description}: -@code{ICHAR(C)} returns the code for the character in the first character -position of @code{C} in the system's native character set. -The correspondence between characters and their codes is not necessarily -the same across different GNU Fortran implementations. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ICHAR(C [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - -@item @emph{Example}: -@smallexample -program test_ichar - integer i - i = ichar(' ') -end program test_ichar -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later -@end multitable - -@item @emph{Note}: -No intrinsic exists to convert between a numeric value and a formatted -character string representation -- for instance, given the -@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or -@code{REAL} value with the value 154, or vice versa. Instead, this -functionality is provided by internal-file I/O, as in the following -example: -@smallexample -program read_val - integer value - character(len=10) string, string2 - string = '154' - - ! Convert a string to a numeric value - read (string,'(I10)') value - print *, value - - ! Convert a value to a formatted string - write (string2,'(I10)') value - print *, string2 -end program read_val -@end smallexample - -@item @emph{See also}: -@ref{ACHAR}, @ref{CHAR}, @ref{IACHAR} - -@end table - - - -@node IDATE -@section @code{IDATE} --- Get current local time subroutine (day/month/year) -@fnindex IDATE -@cindex date, current -@cindex current date - -@table @asis -@item @emph{Description}: -@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the -current local time. The day (in the range 1-31), month (in the range 1-12), -and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. -The year has four significant digits. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL IDATE(VALUES)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and -the kind shall be the default integer kind. -@end multitable - -@item @emph{Return value}: -Does not return anything. - -@item @emph{Example}: -@smallexample -program test_idate - integer, dimension(3) :: tarray - call idate(tarray) - print *, tarray(1) - print *, tarray(2) - print *, tarray(3) -end program test_idate -@end smallexample -@end table - - - -@node IEOR -@section @code{IEOR} --- Bitwise logical exclusive or -@fnindex IEOR -@cindex bitwise logical exclusive or -@cindex logical exclusive or, bitwise - -@table @asis -@item @emph{Description}: -@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and -@var{J}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IEOR(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{J} @tab The type shall be @code{INTEGER}, of the same -kind as @var{I}. (As a GNU extension, different kinds are also -permitted.) -@end multitable - -@item @emph{Return value}: -The return type is @code{INTEGER}, of the same kind as the -arguments. (If the argument kinds differ, it is of the same kind as -the larger argument.) - -@item @emph{See also}: -@ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} -@end table - - - -@node IERRNO -@section @code{IERRNO} --- Get the last system error number -@fnindex IERRNO -@cindex system, error handling - -@table @asis -@item @emph{Description}: -Returns the last system error number, as given by the C @code{errno} -variable. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = IERRNO()} - -@item @emph{Arguments}: -None. - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. - -@item @emph{See also}: -@ref{PERROR} -@end table - - - -@node IMAGE_INDEX -@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index -@fnindex IMAGE_INDEX -@cindex coarray, @code{IMAGE_INDEX} -@cindex images, cosubscript to image index conversion - -@table @asis -@item @emph{Description}: -Returns the image index belonging to a cosubscript. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Inquiry function. - -@item @emph{Syntax}: -@code{RESULT = IMAGE_INDEX(COARRAY, SUB)} - -@item @emph{Arguments}: None. -@multitable @columnfractions .15 .70 -@item @var{COARRAY} @tab Coarray of any type. -@item @var{SUB} @tab default integer rank-1 array of a size equal to -the corank of @var{COARRAY}. -@end multitable - - -@item @emph{Return value}: -Scalar default integer with the value of the image index which corresponds -to the cosubscripts. For invalid cosubscripts the result is zero. - -@item @emph{Example}: -@smallexample -INTEGER :: array[2,-1:4,8,*] -! Writes 28 (or 0 if there are fewer than 28 images) -WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) -@end smallexample - -@item @emph{See also}: -@ref{THIS_IMAGE}, @ref{NUM_IMAGES} -@end table - - - -@node INDEX intrinsic -@section @code{INDEX} --- Position of a substring within a string -@fnindex INDEX -@cindex substring position -@cindex string, find substring - -@table @asis -@item @emph{Description}: -Returns the position of the start of the first occurrence of string -@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If -@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If -the @var{BACK} argument is present and true, the return value is the -start of the last occurrence rather than the first. - -@item @emph{Standard}: -Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with -@code{INTENT(IN)} -@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with -@code{INTENT(IN)} -@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with -@code{INTENT(IN)} -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -@ref{SCAN}, @ref{VERIFY} -@end table - - - -@node INT -@section @code{INT} --- Convert to integer type -@fnindex INT -@fnindex IFIX -@fnindex IDINT -@cindex conversion, to integer - -@table @asis -@item @emph{Description}: -Convert to integer type - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = INT(A [, KIND))} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be of type @code{INTEGER}, -@code{REAL}, or @code{COMPLEX}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -These functions return a @code{INTEGER} variable or array under -the following rules: - -@table @asis -@item (A) -If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} -@item (B) -If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}. -If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed -the range of @var{A} and whose sign is the same as the sign of @var{A}. -@item (C) -If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. -@end table - -@item @emph{Example}: -@smallexample -program test_int - integer :: i = 42 - complex :: z = (-3.7, 1.0) - print *, int(i) - print *, int(z), int(z,8) -end program -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later -@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later -@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later -@end multitable - -@end table - - -@node INT2 -@section @code{INT2} --- Convert to 16-bit integer type -@fnindex INT2 -@fnindex SHORT -@cindex conversion, to integer - -@table @asis -@item @emph{Description}: -Convert to a @code{KIND=2} integer type. This is equivalent to the -standard @code{INT} intrinsic with an optional argument of -@code{KIND=2}, and is only included for backwards compatibility. - -The @code{SHORT} intrinsic is equivalent to @code{INT2}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = INT2(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be of type @code{INTEGER}, -@code{REAL}, or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is a @code{INTEGER(2)} variable. - -@item @emph{See also}: -@ref{INT}, @ref{INT8}, @ref{LONG} -@end table - - - -@node INT8 -@section @code{INT8} --- Convert to 64-bit integer type -@fnindex INT8 -@cindex conversion, to integer - -@table @asis -@item @emph{Description}: -Convert to a @code{KIND=8} integer type. This is equivalent to the -standard @code{INT} intrinsic with an optional argument of -@code{KIND=8}, and is only included for backwards compatibility. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = INT8(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be of type @code{INTEGER}, -@code{REAL}, or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is a @code{INTEGER(8)} variable. - -@item @emph{See also}: -@ref{INT}, @ref{INT2}, @ref{LONG} -@end table - - - -@node IOR -@section @code{IOR} --- Bitwise logical or -@fnindex IOR -@cindex bitwise logical or -@cindex logical or, bitwise - -@table @asis -@item @emph{Description}: -@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and -@var{J}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IOR(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{J} @tab The type shall be @code{INTEGER}, of the same -kind as @var{I}. (As a GNU extension, different kinds are also -permitted.) -@end multitable - -@item @emph{Return value}: -The return type is @code{INTEGER}, of the same kind as the -arguments. (If the argument kinds differ, it is of the same kind as -the larger argument.) - -@item @emph{See also}: -@ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} -@end table - - - -@node IPARITY -@section @code{IPARITY} --- Bitwise XOR of array elements -@fnindex IPARITY -@cindex array, parity -@cindex array, XOR -@cindex bits, XOR of array elements - -@table @asis -@item @emph{Description}: -Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along -dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = IPARITY(ARRAY[, MASK])} -@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} -@item @var{DIM} @tab (Optional) shall be a scalar of type -@code{INTEGER} with a value in the range from 1 to n, where n -equals the rank of @var{ARRAY}. -@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} -and either be a scalar or an array of the same shape as @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as @var{ARRAY}. - -If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in -@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals -the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with -dimension @var{DIM} dropped is returned. - -@item @emph{Example}: -@smallexample -PROGRAM test_iparity - INTEGER(1) :: a(2) - - a(1) = b'00100100' - a(2) = b'01101010' - - ! prints 01001110 - PRINT '(b8.8)', IPARITY(a) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY} -@end table - - - -@node IRAND -@section @code{IRAND} --- Integer pseudo-random number -@fnindex IRAND -@cindex random number generation - -@table @asis -@item @emph{Description}: -@code{IRAND(FLAG)} returns a pseudo-random number from a uniform -distribution between 0 and a system-dependent limit (which is in most -cases 2147483647). If @var{FLAG} is 0, the next number -in the current sequence is returned; if @var{FLAG} is 1, the generator -is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, -it is used as a new seed with @code{SRAND}. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. It implements a simple modulo generator as provided -by @command{g77}. For new code, one should consider the use of -@ref{RANDOM_NUMBER} as it implements a superior algorithm. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = IRAND(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. -@end multitable - -@item @emph{Return value}: -The return value is of @code{INTEGER(kind=4)} type. - -@item @emph{Example}: -@smallexample -program test_irand - integer,parameter :: seed = 86456 - - call srand(seed) - print *, irand(), irand(), irand(), irand() - print *, irand(seed), irand(), irand(), irand() -end program test_irand -@end smallexample - -@end table - - - -@node IS_IOSTAT_END -@section @code{IS_IOSTAT_END} --- Test for end-of-file value -@fnindex IS_IOSTAT_END -@cindex @code{IOSTAT}, end of file - -@table @asis -@item @emph{Description}: -@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O -status ``end of file''. The function is equivalent to comparing the variable -with the @code{IOSTAT_END} parameter of the intrinsic module -@code{ISO_FORTRAN_ENV}. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IS_IOSTAT_END(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of the type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if -@var{I} has the value which indicates an end of file condition for -@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. - -@item @emph{Example}: -@smallexample -PROGRAM iostat - IMPLICIT NONE - INTEGER :: stat, i - OPEN(88, FILE='test.dat') - READ(88, *, IOSTAT=stat) i - IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' -END PROGRAM -@end smallexample -@end table - - - -@node IS_IOSTAT_EOR -@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value -@fnindex IS_IOSTAT_EOR -@cindex @code{IOSTAT}, end of record - -@table @asis -@item @emph{Description}: -@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O -status ``end of record''. The function is equivalent to comparing the -variable with the @code{IOSTAT_EOR} parameter of the intrinsic module -@code{ISO_FORTRAN_ENV}. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = IS_IOSTAT_EOR(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of the type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if -@var{I} has the value which indicates an end of file condition for -@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. - -@item @emph{Example}: -@smallexample -PROGRAM iostat - IMPLICIT NONE - INTEGER :: stat, i(50) - OPEN(88, FILE='test.dat', FORM='UNFORMATTED') - READ(88, IOSTAT=stat) i - IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' -END PROGRAM -@end smallexample -@end table - - - -@node ISATTY -@section @code{ISATTY} --- Whether a unit is a terminal device. -@fnindex ISATTY -@cindex system, terminal - -@table @asis -@item @emph{Description}: -Determine whether a unit is connected to a terminal device. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = ISATTY(UNIT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal -device, @code{.FALSE.} otherwise. - -@item @emph{Example}: -@smallexample -PROGRAM test_isatty - INTEGER(kind=1) :: unit - DO unit = 1, 10 - write(*,*) isatty(unit=unit) - END DO -END PROGRAM -@end smallexample -@item @emph{See also}: -@ref{TTYNAM} -@end table - - - -@node ISHFT -@section @code{ISHFT} --- Shift bits -@fnindex ISHFT -@cindex bits, shift - -@table @asis -@item @emph{Description}: -@code{ISHFT} returns a value corresponding to @var{I} with all of the -bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than -zero corresponds to a left shift, a value of zero corresponds to no -shift, and a value less than zero corresponds to a right shift. If the -absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the -value is undefined. Bits shifted out from the left end or right end are -lost; zeros are shifted in from the opposite end. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ISHFT(I, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{ISHFTC} -@end table - - - -@node ISHFTC -@section @code{ISHFTC} --- Shift bits circularly -@fnindex ISHFTC -@cindex bits, shift circular - -@table @asis -@item @emph{Description}: -@code{ISHFTC} returns a value corresponding to @var{I} with the -rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that -is, bits shifted out one end are shifted into the opposite end. A value -of @var{SHIFT} greater than zero corresponds to a left shift, a value of -zero corresponds to no shift, and a value less than zero corresponds to -a right shift. The absolute value of @var{SHIFT} must be less than -@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be -equivalent to @code{BIT_SIZE(I)}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = ISHFTC(I, SHIFT [, SIZE])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; -the value must be greater than zero and less than or equal to -@code{BIT_SIZE(I)}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{ISHFT} -@end table - - - -@node ISNAN -@section @code{ISNAN} --- Test for a NaN -@fnindex ISNAN -@cindex IEEE, ISNAN - -@table @asis -@item @emph{Description}: -@code{ISNAN} tests whether a floating-point value is an IEEE -Not-a-Number (NaN). -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{ISNAN(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Variable of the type @code{REAL}. - -@end multitable - -@item @emph{Return value}: -Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} -if @var{X} is a NaN and @code{FALSE} otherwise. - -@item @emph{Example}: -@smallexample -program test_nan - implicit none - real :: x - x = -1.0 - x = sqrt(x) - if (isnan(x)) stop '"x" is a NaN' -end program test_nan -@end smallexample -@end table - - - -@node ITIME -@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) -@fnindex ITIME -@cindex time, current -@cindex current time - -@table @asis -@item @emph{Description}: -@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the -current local time. The hour (in the range 1-24), minute (in the range 1-60), -and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, -respectively. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL ITIME(VALUES)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} -and the kind shall be the default integer kind. -@end multitable - -@item @emph{Return value}: -Does not return anything. - - -@item @emph{Example}: -@smallexample -program test_itime - integer, dimension(3) :: tarray - call itime(tarray) - print *, tarray(1) - print *, tarray(2) - print *, tarray(3) -end program test_itime -@end smallexample -@end table - - - -@node KILL -@section @code{KILL} --- Send a signal to a process -@fnindex KILL - -@table @asis -@item @emph{Description}: -@item @emph{Standard}: -Sends the signal specified by @var{SIGNAL} to the process @var{PID}. -See @code{kill(2)}. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL KILL(C, VALUE [, STATUS])} -@item @code{STATUS = KILL(C, VALUE)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab Shall be a scalar @code{INTEGER}, with -@code{INTENT(IN)} -@item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with -@code{INTENT(IN)} -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or -@code{INTEGER(8)}. Returns 0 on success, or a system-specific error code -otherwise. -@end multitable - -@item @emph{See also}: -@ref{ABORT}, @ref{EXIT} -@end table - - - -@node KIND -@section @code{KIND} --- Kind of an entity -@fnindex KIND -@cindex kind - -@table @asis -@item @emph{Description}: -@code{KIND(X)} returns the kind value of the entity @var{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{K = KIND(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, -@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type @code{INTEGER} and of the default -integer kind. - -@item @emph{Example}: -@smallexample -program test_kind - integer,parameter :: kc = kind(' ') - integer,parameter :: kl = kind(.true.) - - print *, "The default character kind is ", kc - print *, "The default logical kind is ", kl -end program test_kind -@end smallexample - -@end table - - - -@node LBOUND -@section @code{LBOUND} --- Lower dimension bounds of an array -@fnindex LBOUND -@cindex array, lower bound - -@table @asis -@item @emph{Description}: -Returns the lower bounds of an array, or a single lower bound -along the @var{DIM} dimension. -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array, of any type. -@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. -If @var{DIM} is absent, the result is an array of the lower bounds of -@var{ARRAY}. If @var{DIM} is present, the result is a scalar -corresponding to the lower bound of the array along that dimension. If -@var{ARRAY} is an expression rather than a whole array or array -structure component, or if it has a zero extent along the relevant -dimension, the lower bound is taken to be 1. - -@item @emph{See also}: -@ref{UBOUND}, @ref{LCOBOUND} -@end table - - - -@node LCOBOUND -@section @code{LCOBOUND} --- Lower codimension bounds of an array -@fnindex LCOBOUND -@cindex coarray, lower bound - -@table @asis -@item @emph{Description}: -Returns the lower bounds of a coarray, or a single lower cobound -along the @var{DIM} codimension. -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an coarray, of any type. -@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. -If @var{DIM} is absent, the result is an array of the lower cobounds of -@var{COARRAY}. If @var{DIM} is present, the result is a scalar -corresponding to the lower cobound of the array along that codimension. - -@item @emph{See also}: -@ref{UCOBOUND}, @ref{LBOUND} -@end table - - - -@node LEADZ -@section @code{LEADZ} --- Number of leading zero bits of an integer -@fnindex LEADZ -@cindex zero bits - -@table @asis -@item @emph{Description}: -@code{LEADZ} returns the number of leading zero bits of an integer. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LEADZ(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The type of the return value is the default @code{INTEGER}. -If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. - -@item @emph{Example}: -@smallexample -PROGRAM test_leadz - WRITE (*,*) BIT_SIZE(1) ! prints 32 - WRITE (*,*) LEADZ(1) ! prints 31 -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR} -@end table - - - -@node LEN -@section @code{LEN} --- Length of a character entity -@fnindex LEN -@cindex string, length - -@table @asis -@item @emph{Description}: -Returns the length of a character string. If @var{STRING} is an array, -the length of an element of @var{STRING} is returned. Note that -@var{STRING} need not be defined when this intrinsic is invoked, since -only the length, not the content, of @var{STRING} is needed. - -@item @emph{Standard}: -Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{L = LEN(STRING [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be a scalar or array of type -@code{CHARACTER}, with @code{INTENT(IN)} -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later -@end multitable - - -@item @emph{See also}: -@ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR} -@end table - - - -@node LEN_TRIM -@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters -@fnindex LEN_TRIM -@cindex string, length, without trailing whitespace - -@table @asis -@item @emph{Description}: -Returns the length of a character string, ignoring any trailing blanks. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LEN_TRIM(STRING [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, -with @code{INTENT(IN)} -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - -@item @emph{See also}: -@ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR} -@end table - - - -@node LGE -@section @code{LGE} --- Lexical greater than or equal -@fnindex LGE -@cindex lexical comparison of strings -@cindex string, comparison - -@table @asis -@item @emph{Description}: -Determines whether one string is lexically greater than or equal to -another string, where the two strings are interpreted as containing -ASCII character codes. If the String A and String B are not the same -length, the shorter is compared as if spaces were appended to it to form -a value that has the same length as the longer. - -In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, -@code{LLE}, and @code{LLT} differ from the corresponding intrinsic -operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in -that the latter use the processor's character ordering (which is not -ASCII on some targets), whereas the former always use the ASCII -ordering. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LGE(STRING_A, STRING_B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. -@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. -@end multitable - -@item @emph{Return value}: -Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} -otherwise, based on the ASCII ordering. - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -@ref{LGT}, @ref{LLE}, @ref{LLT} -@end table - - - -@node LGT -@section @code{LGT} --- Lexical greater than -@fnindex LGT -@cindex lexical comparison of strings -@cindex string, comparison - -@table @asis -@item @emph{Description}: -Determines whether one string is lexically greater than another string, -where the two strings are interpreted as containing ASCII character -codes. If the String A and String B are not the same length, the -shorter is compared as if spaces were appended to it to form a value -that has the same length as the longer. - -In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, -@code{LLE}, and @code{LLT} differ from the corresponding intrinsic -operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in -that the latter use the processor's character ordering (which is not -ASCII on some targets), whereas the former always use the ASCII -ordering. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LGT(STRING_A, STRING_B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. -@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. -@end multitable - -@item @emph{Return value}: -Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} -otherwise, based on the ASCII ordering. - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -@ref{LGE}, @ref{LLE}, @ref{LLT} -@end table - - - -@node LINK -@section @code{LINK} --- Create a hard link -@fnindex LINK -@cindex file system, create link -@cindex file system, hard link - -@table @asis -@item @emph{Description}: -Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null -character (@code{CHAR(0)}) can be used to mark the end of the names in -@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file -names are ignored. If the @var{STATUS} argument is supplied, it -contains 0 on success or a nonzero error code upon return; see -@code{link(2)}. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL LINK(PATH1, PATH2 [, STATUS])} -@item @code{STATUS = LINK(PATH1, PATH2)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. -@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. -@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. -@end multitable - -@item @emph{See also}: -@ref{SYMLNK}, @ref{UNLINK} -@end table - - - -@node LLE -@section @code{LLE} --- Lexical less than or equal -@fnindex LLE -@cindex lexical comparison of strings -@cindex string, comparison - -@table @asis -@item @emph{Description}: -Determines whether one string is lexically less than or equal to another -string, where the two strings are interpreted as containing ASCII -character codes. If the String A and String B are not the same length, -the shorter is compared as if spaces were appended to it to form a value -that has the same length as the longer. - -In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, -@code{LLE}, and @code{LLT} differ from the corresponding intrinsic -operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in -that the latter use the processor's character ordering (which is not -ASCII on some targets), whereas the former always use the ASCII -ordering. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LLE(STRING_A, STRING_B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. -@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. -@end multitable - -@item @emph{Return value}: -Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} -otherwise, based on the ASCII ordering. - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -@ref{LGE}, @ref{LGT}, @ref{LLT} -@end table - - - -@node LLT -@section @code{LLT} --- Lexical less than -@fnindex LLT -@cindex lexical comparison of strings -@cindex string, comparison - -@table @asis -@item @emph{Description}: -Determines whether one string is lexically less than another string, -where the two strings are interpreted as containing ASCII character -codes. If the String A and String B are not the same length, the -shorter is compared as if spaces were appended to it to form a value -that has the same length as the longer. - -In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, -@code{LLE}, and @code{LLT} differ from the corresponding intrinsic -operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in -that the latter use the processor's character ordering (which is not -ASCII on some targets), whereas the former always use the ASCII -ordering. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LLT(STRING_A, STRING_B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. -@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. -@end multitable - -@item @emph{Return value}: -Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} -otherwise, based on the ASCII ordering. - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -@ref{LGE}, @ref{LGT}, @ref{LLE} -@end table - - - -@node LNBLNK -@section @code{LNBLNK} --- Index of the last non-blank character in a string -@fnindex LNBLNK -@cindex string, find non-blank character - -@table @asis -@item @emph{Description}: -Returns the length of a character string, ignoring any trailing blanks. -This is identical to the standard @code{LEN_TRIM} intrinsic, and is only -included for backwards compatibility. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LNBLNK(STRING)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, -with @code{INTENT(IN)} -@end multitable - -@item @emph{Return value}: -The return value is of @code{INTEGER(kind=4)} type. - -@item @emph{See also}: -@ref{INDEX intrinsic}, @ref{LEN_TRIM} -@end table - - - -@node LOC -@section @code{LOC} --- Returns the address of a variable -@fnindex LOC -@cindex location of a variable in memory - -@table @asis -@item @emph{Description}: -@code{LOC(X)} returns the address of @var{X} as an integer. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = LOC(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Variable of any type. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER}, with a @code{KIND} -corresponding to the size (in bytes) of a memory address on the target -machine. - -@item @emph{Example}: -@smallexample -program test_loc - integer :: i - real :: r - i = loc(r) - print *, i -end program test_loc -@end smallexample -@end table - - - -@node LOG -@section @code{LOG} --- Natural logarithm function -@fnindex LOG -@fnindex ALOG -@fnindex DLOG -@fnindex CLOG -@fnindex ZLOG -@fnindex CDLOG -@cindex exponential function, inverse -@cindex logarithm function -@cindex natural logarithm function - -@table @asis -@item @emph{Description}: -@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the -logarithm to the base @math{e}. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LOG(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or -@code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} or @code{COMPLEX}. -The kind type parameter is the same as @var{X}. -If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range -@math{-\pi \leq \omega \leq \pi}. - -@item @emph{Example}: -@smallexample -program test_log - real(8) :: x = 2.7182818284590451_8 - complex :: z = (1.0, 2.0) - x = log(x) ! will yield (approximately) 1 - z = log(z) -end program test_log -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu -@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu -@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu -@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu -@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu -@end multitable -@end table - - - -@node LOG10 -@section @code{LOG10} --- Base 10 logarithm function -@fnindex LOG10 -@fnindex ALOG10 -@fnindex DLOG10 -@cindex exponential function, inverse -@cindex logarithm function with base 10 -@cindex base 10 logarithm function - -@table @asis -@item @emph{Description}: -@code{LOG10(X)} computes the base 10 logarithm of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LOG10(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} or @code{COMPLEX}. -The kind type parameter is the same as @var{X}. - -@item @emph{Example}: -@smallexample -program test_log10 - real(8) :: x = 10.0_8 - x = log10(x) -end program test_log10 -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later -@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later -@end multitable -@end table - - - -@node LOG_GAMMA -@section @code{LOG_GAMMA} --- Logarithm of the Gamma function -@fnindex LOG_GAMMA -@fnindex LGAMMA -@fnindex ALGAMA -@fnindex DLGAMA -@cindex Gamma function, logarithm of - -@table @asis -@item @emph{Description}: -@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value -of the Gamma (@math{\Gamma}) function. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{X = LOG_GAMMA(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL} and neither zero -nor a negative integer. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} of the same kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_log_gamma - real :: x = 1.0 - x = lgamma(x) ! returns 0.0 -end program test_log_gamma -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension -@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension -@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension -@end multitable - -@item @emph{See also}: -Gamma function: @ref{GAMMA} - -@end table - - - -@node LOGICAL -@section @code{LOGICAL} --- Convert to logical type -@fnindex LOGICAL -@cindex conversion, to logical - -@table @asis -@item @emph{Description}: -Converts one kind of @code{LOGICAL} variable to another. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LOGICAL(L [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{L} @tab The type shall be @code{LOGICAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is a @code{LOGICAL} value equal to @var{L}, with a -kind corresponding to @var{KIND}, or of the default logical kind if -@var{KIND} is not given. - -@item @emph{See also}: -@ref{INT}, @ref{REAL}, @ref{CMPLX} -@end table - - - -@node LONG -@section @code{LONG} --- Convert to integer type -@fnindex LONG -@cindex conversion, to integer - -@table @asis -@item @emph{Description}: -Convert to a @code{KIND=4} integer type, which is the same size as a C -@code{long} integer. This is equivalent to the standard @code{INT} -intrinsic with an optional argument of @code{KIND=4}, and is only -included for backwards compatibility. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LONG(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be of type @code{INTEGER}, -@code{REAL}, or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is a @code{INTEGER(4)} variable. - -@item @emph{See also}: -@ref{INT}, @ref{INT2}, @ref{INT8} -@end table - - - -@node LSHIFT -@section @code{LSHIFT} --- Left shift bits -@fnindex LSHIFT -@cindex bits, shift left - -@table @asis -@item @emph{Description}: -@code{LSHIFT} returns a value corresponding to @var{I} with all of the -bits shifted left by @var{SHIFT} places. If the absolute value of -@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. -Bits shifted out from the left end are lost; zeros are shifted in from -the opposite end. - -This function has been superseded by the @code{ISHFT} intrinsic, which -is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, -which is standard in Fortran 2008 and later. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = LSHIFT(I, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL}, -@ref{SHIFTR} - -@end table - - - -@node LSTAT -@section @code{LSTAT} --- Get file status -@fnindex LSTAT -@cindex file system, file status - -@table @asis -@item @emph{Description}: -@code{LSTAT} is identical to @ref{STAT}, except that if path is a -symbolic link, then the link itself is statted, not the file that it -refers to. - -The elements in @code{VALUES} are the same as described by @ref{STAT}. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL LSTAT(NAME, VALUES [, STATUS])} -@item @code{STATUS = LSTAT(NAME, VALUES)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default -kind, a valid path within the file system. -@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. -Returns 0 on success and a system specific error code otherwise. -@end multitable - -@item @emph{Example}: -See @ref{STAT} for an example. - -@item @emph{See also}: -To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT} -@end table - - - -@node LTIME -@section @code{LTIME} --- Convert time to local time info -@fnindex LTIME -@cindex time, conversion to local time info - -@table @asis -@item @emph{Description}: -Given a system time value @var{TIME} (as provided by the @code{TIME8} -intrinsic), fills @var{VALUES} with values extracted from it appropriate -to the local time zone using @code{localtime(3)}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL LTIME(TIME, VALUES)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{TIME} @tab An @code{INTEGER} scalar expression -corresponding to a system time, with @code{INTENT(IN)}. -@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, -with @code{INTENT(OUT)}. -@end multitable - -@item @emph{Return value}: -The elements of @var{VALUES} are assigned as follows: -@enumerate -@item Seconds after the minute, range 0--59 or 0--61 to allow for leap -seconds -@item Minutes after the hour, range 0--59 -@item Hours past midnight, range 0--23 -@item Day of month, range 0--31 -@item Number of months since January, range 0--12 -@item Years since 1900 -@item Number of days since Sunday, range 0--6 -@item Days since January 1 -@item Daylight savings indicator: positive if daylight savings is in -effect, zero if not, and negative if the information is not available. -@end enumerate - -@item @emph{See also}: -@ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8} - -@end table - - - -@node MALLOC -@section @code{MALLOC} --- Allocate dynamic memory -@fnindex MALLOC -@cindex pointer, cray - -@table @asis -@item @emph{Description}: -@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and -returns the address of the allocated memory. The @code{MALLOC} intrinsic -is an extension intended to be used with Cray pointers, and is provided -in GNU Fortran to allow the user to compile legacy code. For new code -using Fortran 95 pointers, the memory allocation intrinsic is -@code{ALLOCATE}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{PTR = MALLOC(SIZE)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SIZE} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER(K)}, with @var{K} such that -variables of type @code{INTEGER(K)} have the same size as -C pointers (@code{sizeof(void *)}). - -@item @emph{Example}: -The following example demonstrates the use of @code{MALLOC} and -@code{FREE} with Cray pointers. - -@smallexample -program test_malloc - implicit none - integer i - real*8 x(*), z - pointer(ptr_x,x) - - ptr_x = malloc(20*8) - do i = 1, 20 - x(i) = sqrt(1.0d0 / i) - end do - z = 0 - do i = 1, 20 - z = z + x(i) - print *, z - end do - call free(ptr_x) -end program test_malloc -@end smallexample - -@item @emph{See also}: -@ref{FREE} -@end table - - - -@node MASKL -@section @code{MASKL} --- Left justified mask -@fnindex MASKL -@cindex mask, left justified - -@table @asis -@item @emph{Description}: -@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the -remaining bits set to 0. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MASKL(I[, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER}. -@item @var{KIND} @tab Shall be a scalar constant expression of type -@code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER}. If @var{KIND} is present, it -specifies the kind value of the return type; otherwise, it is of the -default integer kind. - -@item @emph{See also}: -@ref{MASKR} -@end table - - - -@node MASKR -@section @code{MASKR} --- Right justified mask -@fnindex MASKR -@cindex mask, right justified - -@table @asis -@item @emph{Description}: -@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the -remaining bits set to 0. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MASKR(I[, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER}. -@item @var{KIND} @tab Shall be a scalar constant expression of type -@code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER}. If @var{KIND} is present, it -specifies the kind value of the return type; otherwise, it is of the -default integer kind. - -@item @emph{See also}: -@ref{MASKL} -@end table - - - -@node MATMUL -@section @code{MATMUL} --- matrix multiplication -@fnindex MATMUL -@cindex matrix multiplication -@cindex product, matrix - -@table @asis -@item @emph{Description}: -Performs a matrix multiplication on numeric or logical arguments. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{MATRIX_A} @tab An array of @code{INTEGER}, -@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of -one or two. -@item @var{MATRIX_B} @tab An array of @code{INTEGER}, -@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric -type; otherwise, an array of @code{LOGICAL} type. The rank shall be one -or two, and the first (or only) dimension of @var{MATRIX_B} shall be -equal to the last (or only) dimension of @var{MATRIX_A}. -@end multitable - -@item @emph{Return value}: -The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and -kind of the result follow the usual type and kind promotion rules, as -for the @code{*} or @code{.AND.} operators. - -@item @emph{See also}: -@end table - - - -@node MAX -@section @code{MAX} --- Maximum value of an argument list -@fnindex MAX -@fnindex MAX0 -@fnindex AMAX0 -@fnindex MAX1 -@fnindex AMAX1 -@fnindex DMAX1 -@cindex maximum value - -@table @asis -@item @emph{Description}: -Returns the argument with the largest (most positive) value. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MAX(A1, A2 [, A3 [, ...]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A1} @tab The type shall be @code{INTEGER} or -@code{REAL}. -@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind -as @var{A1}. (As a GNU extension, arguments of different kinds are -permitted.) -@end multitable - -@item @emph{Return value}: -The return value corresponds to the maximum value among the arguments, -and has the same type and kind as the first argument. - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later -@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later -@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later -@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -@ref{MAXLOC} @ref{MAXVAL}, @ref{MIN} - -@end table - - - -@node MAXEXPONENT -@section @code{MAXEXPONENT} --- Maximum exponent of a real kind -@fnindex MAXEXPONENT -@cindex model representation, maximum exponent - -@table @asis -@item @emph{Description}: -@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the -type of @code{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = MAXEXPONENT(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. - -@item @emph{Example}: -@smallexample -program exponents - real(kind=4) :: x - real(kind=8) :: y - - print *, minexponent(x), maxexponent(x) - print *, minexponent(y), maxexponent(y) -end program exponents -@end smallexample -@end table - - - -@node MAXLOC -@section @code{MAXLOC} --- Location of the maximum value within an array -@fnindex MAXLOC -@cindex array, location of maximum element - -@table @asis -@item @emph{Description}: -Determines the location of the element in the array with the maximum -value, or, if the @var{DIM} argument is supplied, determines the -locations of the maximum element along each row of the array in the -@var{DIM} direction. If @var{MASK} is present, only the elements for -which @var{MASK} is @code{.TRUE.} are considered. If more than one -element in the array has the maximum value, the location returned is -that of the first such element in array element order. If the array has -zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then -the result is an array of zeroes. Similarly, if @var{DIM} is supplied -and all of the elements of @var{MASK} along a given row are zero, the -result value for that row is zero. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])} -@item @code{RESULT = MAXLOC(ARRAY [, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or -@code{REAL}. -@item @var{DIM} @tab (Optional) Shall be a scalar of type -@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, -inclusive. It may not be an optional dummy argument. -@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, -and conformable with @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -If @var{DIM} is absent, the result is a rank-one array with a length -equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result -is an array with a rank one less than the rank of @var{ARRAY}, and a -size corresponding to the size of @var{ARRAY} with the @var{DIM} -dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank -of one, the result is a scalar. In all cases, the result is of default -@code{INTEGER} type. - -@item @emph{See also}: -@ref{MAX}, @ref{MAXVAL} - -@end table - - - -@node MAXVAL -@section @code{MAXVAL} --- Maximum value of an array -@fnindex MAXVAL -@cindex array, maximum value -@cindex maximum value - -@table @asis -@item @emph{Description}: -Determines the maximum value of the elements in an array value, or, if -the @var{DIM} argument is supplied, determines the maximum value along -each row of the array in the @var{DIM} direction. If @var{MASK} is -present, only the elements for which @var{MASK} is @code{.TRUE.} are -considered. If the array has zero size, or all of the elements of -@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} -if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character -type. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} -@item @code{RESULT = MAXVAL(ARRAY [, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or -@code{REAL}. -@item @var{DIM} @tab (Optional) Shall be a scalar of type -@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, -inclusive. It may not be an optional dummy argument. -@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, -and conformable with @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result -is a scalar. If @var{DIM} is present, the result is an array with a -rank one less than the rank of @var{ARRAY}, and a size corresponding to -the size of @var{ARRAY} with the @var{DIM} dimension removed. In all -cases, the result is of the same type and kind as @var{ARRAY}. - -@item @emph{See also}: -@ref{MAX}, @ref{MAXLOC} -@end table - - - -@node MCLOCK -@section @code{MCLOCK} --- Time function -@fnindex MCLOCK -@cindex time, clock ticks -@cindex clock ticks - -@table @asis -@item @emph{Description}: -Returns the number of clock ticks since the start of the process, based -on the function @code{clock(3)} in the C standard library. - -This intrinsic is not fully portable, such as to systems with 32-bit -@code{INTEGER} types but supporting times wider than 32 bits. Therefore, -the values returned by this intrinsic might be, or become, negative, or -numerically less than previous values, during a single run of the -compiled program. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = MCLOCK()} - -@item @emph{Return value}: -The return value is a scalar of type @code{INTEGER(4)}, equal to the -number of clock ticks since the start of the process, or @code{-1} if -the system does not support @code{clock(3)}. - -@item @emph{See also}: -@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME} - -@end table - - - -@node MCLOCK8 -@section @code{MCLOCK8} --- Time function (64-bit) -@fnindex MCLOCK8 -@cindex time, clock ticks -@cindex clock ticks - -@table @asis -@item @emph{Description}: -Returns the number of clock ticks since the start of the process, based -on the function @code{clock(3)} in the C standard library. - -@emph{Warning:} this intrinsic does not increase the range of the timing -values over that returned by @code{clock(3)}. On a system with a 32-bit -@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though -it is converted to a 64-bit @code{INTEGER(8)} value. That means -overflows of the 32-bit value can still occur. Therefore, the values -returned by this intrinsic might be or become negative or numerically -less than previous values during a single run of the compiled program. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = MCLOCK8()} - -@item @emph{Return value}: -The return value is a scalar of type @code{INTEGER(8)}, equal to the -number of clock ticks since the start of the process, or @code{-1} if -the system does not support @code{clock(3)}. - -@item @emph{See also}: -@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} - -@end table - - - -@node MERGE -@section @code{MERGE} --- Merge variables -@fnindex MERGE -@cindex array, merge arrays -@cindex array, combine arrays - -@table @asis -@item @emph{Description}: -Select values from two arrays according to a logical mask. The result -is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to -@var{FSOURCE} if it is @code{.FALSE.}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{TSOURCE} @tab May be of any type. -@item @var{FSOURCE} @tab Shall be of the same type and type parameters -as @var{TSOURCE}. -@item @var{MASK} @tab Shall be of type @code{LOGICAL}. -@end multitable - -@item @emph{Return value}: -The result is of the same type and type parameters as @var{TSOURCE}. - -@end table - - - -@node MERGE_BITS -@section @code{MERGE_BITS} --- Merge of bits under mask -@fnindex MERGE_BITS -@cindex bits, merge - -@table @asis -@item @emph{Description}: -@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} -as determined by the mask. The i-th bit of the result is equal to the -i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to -the i-th bit of @var{J} otherwise. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MERGE_BITS(I, J, MASK)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER}. -@item @var{J} @tab Shall be of type @code{INTEGER} and of the same -kind as @var{I}. -@item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same -kind as @var{I}. -@end multitable - -@item @emph{Return value}: -The result is of the same type and kind as @var{I}. - -@end table - - - -@node MIN -@section @code{MIN} --- Minimum value of an argument list -@fnindex MIN -@fnindex MIN0 -@fnindex AMIN0 -@fnindex MIN1 -@fnindex AMIN1 -@fnindex DMIN1 -@cindex minimum value - -@table @asis -@item @emph{Description}: -Returns the argument with the smallest (most negative) value. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MIN(A1, A2 [, A3, ...])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A1} @tab The type shall be @code{INTEGER} or -@code{REAL}. -@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind -as @var{A1}. (As a GNU extension, arguments of different kinds are -permitted.) -@end multitable - -@item @emph{Return value}: -The return value corresponds to the maximum value among the arguments, -and has the same type and kind as the first argument. - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later -@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later -@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later -@end multitable - -@item @emph{See also}: -@ref{MAX}, @ref{MINLOC}, @ref{MINVAL} -@end table - - - -@node MINEXPONENT -@section @code{MINEXPONENT} --- Minimum exponent of a real kind -@fnindex MINEXPONENT -@cindex model representation, minimum exponent - -@table @asis -@item @emph{Description}: -@code{MINEXPONENT(X)} returns the minimum exponent in the model of the -type of @code{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = MINEXPONENT(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. - -@item @emph{Example}: -See @code{MAXEXPONENT} for an example. -@end table - - - -@node MINLOC -@section @code{MINLOC} --- Location of the minimum value within an array -@fnindex MINLOC -@cindex array, location of minimum element - -@table @asis -@item @emph{Description}: -Determines the location of the element in the array with the minimum -value, or, if the @var{DIM} argument is supplied, determines the -locations of the minimum element along each row of the array in the -@var{DIM} direction. If @var{MASK} is present, only the elements for -which @var{MASK} is @code{.TRUE.} are considered. If more than one -element in the array has the minimum value, the location returned is -that of the first such element in array element order. If the array has -zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then -the result is an array of zeroes. Similarly, if @var{DIM} is supplied -and all of the elements of @var{MASK} along a given row are zero, the -result value for that row is zero. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])} -@item @code{RESULT = MINLOC(ARRAY [, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or -@code{REAL}. -@item @var{DIM} @tab (Optional) Shall be a scalar of type -@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, -inclusive. It may not be an optional dummy argument. -@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, -and conformable with @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -If @var{DIM} is absent, the result is a rank-one array with a length -equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result -is an array with a rank one less than the rank of @var{ARRAY}, and a -size corresponding to the size of @var{ARRAY} with the @var{DIM} -dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank -of one, the result is a scalar. In all cases, the result is of default -@code{INTEGER} type. - -@item @emph{See also}: -@ref{MIN}, @ref{MINVAL} - -@end table - - - -@node MINVAL -@section @code{MINVAL} --- Minimum value of an array -@fnindex MINVAL -@cindex array, minimum value -@cindex minimum value - -@table @asis -@item @emph{Description}: -Determines the minimum value of the elements in an array value, or, if -the @var{DIM} argument is supplied, determines the minimum value along -each row of the array in the @var{DIM} direction. If @var{MASK} is -present, only the elements for which @var{MASK} is @code{.TRUE.} are -considered. If the array has zero size, or all of the elements of -@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if -@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if -@var{ARRAY} is of character type. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} -@item @code{RESULT = MINVAL(ARRAY [, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or -@code{REAL}. -@item @var{DIM} @tab (Optional) Shall be a scalar of type -@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, -inclusive. It may not be an optional dummy argument. -@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, -and conformable with @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result -is a scalar. If @var{DIM} is present, the result is an array with a -rank one less than the rank of @var{ARRAY}, and a size corresponding to -the size of @var{ARRAY} with the @var{DIM} dimension removed. In all -cases, the result is of the same type and kind as @var{ARRAY}. - -@item @emph{See also}: -@ref{MIN}, @ref{MINLOC} - -@end table - - - -@node MOD -@section @code{MOD} --- Remainder function -@fnindex MOD -@fnindex AMOD -@fnindex DMOD -@cindex remainder -@cindex division, remainder - -@table @asis -@item @emph{Description}: -@code{MOD(A,P)} computes the remainder of the division of A by P@. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MOD(A, P)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. -@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} -and not equal to zero. -@end multitable - -@item @emph{Return value}: -The return value is the result of @code{A - (INT(A/P) * P)}. The type -and kind of the return value is the same as that of the arguments. The -returned value has the same sign as A and a magnitude less than the -magnitude of P. - -@item @emph{Example}: -@smallexample -program test_mod - print *, mod(17,3) - print *, mod(17.5,5.5) - print *, mod(17.5d0,5.5) - print *, mod(17.5,5.5d0) - - print *, mod(-17,3) - print *, mod(-17.5,5.5) - print *, mod(-17.5d0,5.5) - print *, mod(-17.5,5.5d0) - - print *, mod(17,-3) - print *, mod(17.5,-5.5) - print *, mod(17.5d0,-5.5) - print *, mod(17.5,-5.5d0) -end program test_mod -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Arguments @tab Return type @tab Standard -@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later -@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later -@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later -@end multitable - -@item @emph{See also}: -@ref{MODULO} - -@end table - - - -@node MODULO -@section @code{MODULO} --- Modulo function -@fnindex MODULO -@cindex modulo -@cindex division, modulo - -@table @asis -@item @emph{Description}: -@code{MODULO(A,P)} computes the @var{A} modulo @var{P}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = MODULO(A, P)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. -@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. -It shall not be zero. -@end multitable - -@item @emph{Return value}: -The type and kind of the result are those of the arguments. -@table @asis -@item If @var{A} and @var{P} are of type @code{INTEGER}: -@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where -@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} -(exclusive). -@item If @var{A} and @var{P} are of type @code{REAL}: -@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. -@end table -The returned value has the same sign as P and a magnitude less than -the magnitude of P. - -@item @emph{Example}: -@smallexample -program test_modulo - print *, modulo(17,3) - print *, modulo(17.5,5.5) - - print *, modulo(-17,3) - print *, modulo(-17.5,5.5) - - print *, modulo(17,-3) - print *, modulo(17.5,-5.5) -end program -@end smallexample - -@item @emph{See also}: -@ref{MOD} - -@end table - - - -@node MOVE_ALLOC -@section @code{MOVE_ALLOC} --- Move allocation from one object to another -@fnindex MOVE_ALLOC -@cindex moving allocation -@cindex allocation, moving - -@table @asis -@item @emph{Description}: -@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to -@var{TO}. @var{FROM} will become deallocated in the process. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Pure subroutine - -@item @emph{Syntax}: -@code{CALL MOVE_ALLOC(FROM, TO)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be -of any type and kind. -@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be -of the same type, kind and rank as @var{FROM}. -@end multitable - -@item @emph{Return value}: -None - -@item @emph{Example}: -@smallexample -program test_move_alloc - integer, allocatable :: a(:), b(:) - - allocate(a(3)) - a = [ 1, 2, 3 ] - call move_alloc(a, b) - print *, allocated(a), allocated(b) - print *, b -end program test_move_alloc -@end smallexample -@end table - - - -@node MVBITS -@section @code{MVBITS} --- Move bits from one integer to another -@fnindex MVBITS -@cindex bits, move - -@table @asis -@item @emph{Description}: -Moves @var{LEN} bits from positions @var{FROMPOS} through -@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through -@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not -affected by the movement of bits is unchanged. The values of -@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than -@code{BIT_SIZE(FROM)}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental subroutine - -@item @emph{Syntax}: -@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{FROM} @tab The type shall be @code{INTEGER}. -@item @var{FROMPOS} @tab The type shall be @code{INTEGER}. -@item @var{LEN} @tab The type shall be @code{INTEGER}. -@item @var{TO} @tab The type shall be @code{INTEGER}, of the -same kind as @var{FROM}. -@item @var{TOPOS} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{See also}: -@ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR} -@end table - - - -@node NEAREST -@section @code{NEAREST} --- Nearest representable number -@fnindex NEAREST -@cindex real number, nearest different -@cindex floating point, nearest different - -@table @asis -@item @emph{Description}: -@code{NEAREST(X, S)} returns the processor-representable number nearest -to @code{X} in the direction indicated by the sign of @code{S}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = NEAREST(X, S)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL}. -@item @var{S} @tab Shall be of type @code{REAL} and -not equal to zero. -@end multitable - -@item @emph{Return value}: -The return value is of the same type as @code{X}. If @code{S} is -positive, @code{NEAREST} returns the processor-representable number -greater than @code{X} and nearest to it. If @code{S} is negative, -@code{NEAREST} returns the processor-representable number smaller than -@code{X} and nearest to it. - -@item @emph{Example}: -@smallexample -program test_nearest - real :: x, y - x = nearest(42.0, 1.0) - y = nearest(42.0, -1.0) - write (*,"(3(G20.15))") x, y, x - y -end program test_nearest -@end smallexample -@end table - - - -@node NEW_LINE -@section @code{NEW_LINE} --- New line character -@fnindex NEW_LINE -@cindex newline -@cindex output, newline - -@table @asis -@item @emph{Description}: -@code{NEW_LINE(C)} returns the new-line character. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = NEW_LINE(C)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{C} @tab The argument shall be a scalar or array of the -type @code{CHARACTER}. -@end multitable - -@item @emph{Return value}: -Returns a @var{CHARACTER} scalar of length one with the new-line character of -the same kind as parameter @var{C}. - -@item @emph{Example}: -@smallexample -program newline - implicit none - write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' -end program newline -@end smallexample -@end table - - - -@node NINT -@section @code{NINT} --- Nearest whole number -@fnindex NINT -@fnindex IDNINT -@cindex rounding, nearest whole number - -@table @asis -@item @emph{Description}: -@code{NINT(A)} rounds its argument to the nearest whole number. - -@item @emph{Standard}: -Fortran 77 and later, with @var{KIND} argument Fortran 90 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = NINT(A [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab The type of the argument shall be @code{REAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -Returns @var{A} with the fractional portion of its magnitude eliminated by -rounding to the nearest whole number and with its sign preserved, -converted to an @code{INTEGER} of the default kind. - -@item @emph{Example}: -@smallexample -program test_nint - real(4) x4 - real(8) x8 - x4 = 1.234E0_4 - x8 = 4.321_8 - print *, nint(x4), idnint(x8) -end program test_nint -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return Type @tab Standard -@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later -@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later -@end multitable - -@item @emph{See also}: -@ref{CEILING}, @ref{FLOOR} - -@end table - - - -@node NORM2 -@section @code{NORM2} --- Euclidean vector norms -@fnindex NORM2 -@cindex Euclidean vector norm -@cindex L2 vector norm -@cindex norm, Euclidean - -@table @asis -@item @emph{Description}: -Calculates the Euclidean vector norm (@math{L_2} norm) of -of @var{ARRAY} along dimension @var{DIM}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = NORM2(ARRAY[, DIM])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{REAL} -@item @var{DIM} @tab (Optional) shall be a scalar of type -@code{INTEGER} with a value in the range from 1 to n, where n -equals the rank of @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as @var{ARRAY}. - -If @var{DIM} is absent, a scalar with the square root of the sum of all -elements in @var{ARRAY} squared is returned. Otherwise, an array of -rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a -shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped -is returned. - -@item @emph{Example}: -@smallexample -PROGRAM test_sum - REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] - print *, NORM2(x) ! = sqrt(55.) ~ 7.416 -END PROGRAM -@end smallexample -@end table - - - -@node NOT -@section @code{NOT} --- Logical negation -@fnindex NOT -@cindex bits, negate -@cindex bitwise logical not -@cindex logical not, bitwise - -@table @asis -@item @emph{Description}: -@code{NOT} returns the bitwise Boolean inverse of @var{I}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = NOT(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return type is @code{INTEGER}, of the same kind as the -argument. - -@item @emph{See also}: -@ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR} - -@end table - - - -@node NULL -@section @code{NULL} --- Function that returns an disassociated pointer -@fnindex NULL -@cindex pointer, status -@cindex pointer, disassociated - -@table @asis -@item @emph{Description}: -Returns a disassociated pointer. - -If @var{MOLD} is present, a disassociated pointer of the same type is -returned, otherwise the type is determined by context. - -In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 -includes cases where it is required. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{PTR => NULL([MOLD])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{MOLD} @tab (Optional) shall be a pointer of any association -status and of any type. -@end multitable - -@item @emph{Return value}: -A disassociated pointer. - -@item @emph{Example}: -@smallexample -REAL, POINTER, DIMENSION(:) :: VEC => NULL () -@end smallexample - -@item @emph{See also}: -@ref{ASSOCIATED} -@end table - - - -@node NUM_IMAGES -@section @code{NUM_IMAGES} --- Function that returns the number of images -@fnindex NUM_IMAGES -@cindex coarray, @code{NUM_IMAGES} -@cindex images, number of - -@table @asis -@item @emph{Description}: -Returns the number of images. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = NUM_IMAGES()} - -@item @emph{Arguments}: None. - -@item @emph{Return value}: -Scalar default-kind integer. - -@item @emph{Example}: -@smallexample -INTEGER :: value[*] -INTEGER :: i -value = THIS_IMAGE() -SYNC ALL -IF (THIS_IMAGE() == 1) THEN - DO i = 1, NUM_IMAGES() - WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] - END DO -END IF -@end smallexample - -@item @emph{See also}: -@ref{THIS_IMAGE}, @ref{IMAGE_INDEX} -@end table - - - -@node OR -@section @code{OR} --- Bitwise logical OR -@fnindex OR -@cindex bitwise logical or -@cindex logical or, bitwise - -@table @asis -@item @emph{Description}: -Bitwise logical @code{OR}. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. For integer arguments, programmers should consider -the use of the @ref{IOR} intrinsic defined by the Fortran standard. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = OR(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be either a scalar @code{INTEGER} -type or a scalar @code{LOGICAL} type. -@item @var{J} @tab The type shall be the same as the type of @var{J}. -@end multitable - -@item @emph{Return value}: -The return type is either a scalar @code{INTEGER} or a scalar -@code{LOGICAL}. If the kind type parameters differ, then the -smaller kind type is implicitly converted to larger kind, and the -return has the larger kind. - -@item @emph{Example}: -@smallexample -PROGRAM test_or - LOGICAL :: T = .TRUE., F = .FALSE. - INTEGER :: a, b - DATA a / Z'F' /, b / Z'3' / - - WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) - WRITE (*,*) OR(a, b) -END PROGRAM -@end smallexample - -@item @emph{See also}: -Fortran 95 elemental function: @ref{IOR} -@end table - - - -@node PACK -@section @code{PACK} --- Pack an array into an array of rank one -@fnindex PACK -@cindex array, packing -@cindex array, reduce dimension -@cindex array, gather elements - -@table @asis -@item @emph{Description}: -Stores the elements of @var{ARRAY} in an array of rank one. - -The beginning of the resulting array is made up of elements whose @var{MASK} -equals @code{TRUE}. Afterwards, positions are filled with elements taken from -@var{VECTOR}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = PACK(ARRAY, MASK[,VECTOR]} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of any type. -@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and -of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} -scalar. -@item @var{VECTOR} @tab (Optional) shall be an array of the same type -as @var{ARRAY} and of rank one. If present, the number of elements in -@var{VECTOR} shall be equal to or greater than the number of true elements -in @var{MASK}. If @var{MASK} is scalar, the number of elements in -@var{VECTOR} shall be equal to or greater than the number of elements in -@var{ARRAY}. -@end multitable - -@item @emph{Return value}: -The result is an array of rank one and the same type as that of @var{ARRAY}. -If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the -number of @code{TRUE} values in @var{MASK} otherwise. - -@item @emph{Example}: -Gathering nonzero elements from an array: -@smallexample -PROGRAM test_pack_1 - INTEGER :: m(6) - m = (/ 1, 0, 0, 0, 5, 0 /) - WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" -END PROGRAM -@end smallexample - -Gathering nonzero elements from an array and appending elements from @var{VECTOR}: -@smallexample -PROGRAM test_pack_2 - INTEGER :: m(4) - m = (/ 1, 0, 0, 2 /) - WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4" -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{UNPACK} -@end table - - - -@node PARITY -@section @code{PARITY} --- Reduction with exclusive OR -@fnindex PARITY -@cindex Parity -@cindex Reduction, XOR -@cindex XOR reduction - -@table @asis -@item @emph{Description}: -Calculates the parity, i.e. the reduction using @code{.XOR.}, -of @var{MASK} along dimension @var{DIM}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = PARITY(MASK[, DIM])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL} -@item @var{DIM} @tab (Optional) shall be a scalar of type -@code{INTEGER} with a value in the range from 1 to n, where n -equals the rank of @var{MASK}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as @var{MASK}. - -If @var{DIM} is absent, a scalar with the parity of all elements in -@var{MASK} is returned, i.e. true if an odd number of elements is -@code{.true.} and false otherwise. If @var{DIM} is present, an array -of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, -and a shape similar to that of @var{MASK} with dimension @var{DIM} -dropped is returned. - -@item @emph{Example}: -@smallexample -PROGRAM test_sum - LOGICAL :: x(2) = [ .true., .false. ] - print *, PARITY(x) ! prints "T" (true). -END PROGRAM -@end smallexample -@end table - - - -@node PERROR -@section @code{PERROR} --- Print system error message -@fnindex PERROR -@cindex system, error handling - -@table @asis -@item @emph{Description}: -Prints (on the C @code{stderr} stream) a newline-terminated error -message corresponding to the last system error. This is prefixed by -@var{STRING}, a colon and a space. See @code{perror(3)}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL PERROR(STRING)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the -default kind. -@end multitable - -@item @emph{See also}: -@ref{IERRNO} -@end table - - - -@node POPCNT -@section @code{POPCNT} --- Number of bits set -@fnindex POPCNT -@cindex binary representation -@cindex bits set - -@table @asis -@item @emph{Description}: -@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary -representation of @code{I}. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = POPCNT(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. - -@item @emph{See also}: -@ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ} - -@item @emph{Example}: -@smallexample -program test_population - print *, popcnt(127), poppar(127) - print *, popcnt(huge(0_4)), poppar(huge(0_4)) - print *, popcnt(huge(0_8)), poppar(huge(0_8)) -end program test_population -@end smallexample -@end table - - -@node POPPAR -@section @code{POPPAR} --- Parity of the number of bits set -@fnindex POPPAR -@cindex binary representation -@cindex parity - -@table @asis -@item @emph{Description}: -@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity -of the number of bits set ('1' bits) in the binary representation of -@code{I}. It is equal to 0 if @code{I} has an even number of bits set, -and 1 for an odd number of '1' bits. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = POPPAR(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. - -@item @emph{See also}: -@ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ} - -@item @emph{Example}: -@smallexample -program test_population - print *, popcnt(127), poppar(127) - print *, popcnt(huge(0_4)), poppar(huge(0_4)) - print *, popcnt(huge(0_8)), poppar(huge(0_8)) -end program test_population -@end smallexample -@end table - - - -@node PRECISION -@section @code{PRECISION} --- Decimal precision of a real kind -@fnindex PRECISION -@cindex model representation, precision - -@table @asis -@item @emph{Description}: -@code{PRECISION(X)} returns the decimal precision in the model of the -type of @code{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = PRECISION(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. - -@item @emph{See also}: -@ref{SELECTED_REAL_KIND}, @ref{RANGE} - -@item @emph{Example}: -@smallexample -program prec_and_range - real(kind=4) :: x(2) - complex(kind=8) :: y - - print *, precision(x), range(x) - print *, precision(y), range(y) -end program prec_and_range -@end smallexample -@end table - - - -@node PRESENT -@section @code{PRESENT} --- Determine whether an optional dummy argument is specified -@fnindex PRESENT - -@table @asis -@item @emph{Description}: -Determines whether an optional dummy argument is present. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = PRESENT(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab May be of any type and may be a pointer, scalar or array -value, or a dummy procedure. It shall be the name of an optional dummy argument -accessible within the current subroutine or function. -@end multitable - -@item @emph{Return value}: -Returns either @code{TRUE} if the optional argument @var{A} is present, or -@code{FALSE} otherwise. - -@item @emph{Example}: -@smallexample -PROGRAM test_present - WRITE(*,*) f(), f(42) ! "F T" -CONTAINS - LOGICAL FUNCTION f(x) - INTEGER, INTENT(IN), OPTIONAL :: x - f = PRESENT(x) - END FUNCTION -END PROGRAM -@end smallexample -@end table - - - -@node PRODUCT -@section @code{PRODUCT} --- Product of array elements -@fnindex PRODUCT -@cindex array, product -@cindex array, multiply elements -@cindex array, conditionally multiply elements -@cindex multiply array elements - -@table @asis -@item @emph{Description}: -Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if -the corresponding element in @var{MASK} is @code{TRUE}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = PRODUCT(ARRAY[, MASK])} -@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, -@code{REAL} or @code{COMPLEX}. -@item @var{DIM} @tab (Optional) shall be a scalar of type -@code{INTEGER} with a value in the range from 1 to n, where n -equals the rank of @var{ARRAY}. -@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} -and either be a scalar or an array of the same shape as @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as @var{ARRAY}. - -If @var{DIM} is absent, a scalar with the product of all elements in -@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals -the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with -dimension @var{DIM} dropped is returned. - - -@item @emph{Example}: -@smallexample -PROGRAM test_product - INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) - print *, PRODUCT(x) ! all elements, product = 120 - print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{SUM} -@end table - - - -@node RADIX -@section @code{RADIX} --- Base of a model number -@fnindex RADIX -@cindex model representation, base -@cindex model representation, radix - -@table @asis -@item @emph{Description}: -@code{RADIX(X)} returns the base of the model representing the entity @var{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = RADIX(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type @code{INTEGER} and of the default -integer kind. - -@item @emph{See also}: -@ref{SELECTED_REAL_KIND} - -@item @emph{Example}: -@smallexample -program test_radix - print *, "The radix for the default integer kind is", radix(0) - print *, "The radix for the default real kind is", radix(0.0) -end program test_radix -@end smallexample - -@end table - - - -@node RAN -@section @code{RAN} --- Real pseudo-random number -@fnindex RAN -@cindex random number generation - -@table @asis -@item @emph{Description}: -For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is -provided as an alias for @code{RAND}. See @ref{RAND} for complete -documentation. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{See also}: -@ref{RAND}, @ref{RANDOM_NUMBER} -@end table - - - -@node RAND -@section @code{RAND} --- Real pseudo-random number -@fnindex RAND -@cindex random number generation - -@table @asis -@item @emph{Description}: -@code{RAND(FLAG)} returns a pseudo-random number from a uniform -distribution between 0 and 1. If @var{FLAG} is 0, the next number -in the current sequence is returned; if @var{FLAG} is 1, the generator -is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, -it is used as a new seed with @code{SRAND}. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. It implements a simple modulo generator as provided -by @command{g77}. For new code, one should consider the use of -@ref{RANDOM_NUMBER} as it implements a superior algorithm. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = RAND(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. -@end multitable - -@item @emph{Return value}: -The return value is of @code{REAL} type and the default kind. - -@item @emph{Example}: -@smallexample -program test_rand - integer,parameter :: seed = 86456 - - call srand(seed) - print *, rand(), rand(), rand(), rand() - print *, rand(seed), rand(), rand(), rand() -end program test_rand -@end smallexample - -@item @emph{See also}: -@ref{SRAND}, @ref{RANDOM_NUMBER} - -@end table - - - -@node RANDOM_NUMBER -@section @code{RANDOM_NUMBER} --- Pseudo-random number -@fnindex RANDOM_NUMBER -@cindex random number generation - -@table @asis -@item @emph{Description}: -Returns a single pseudorandom number or an array of pseudorandom numbers -from the uniform distribution over the range @math{ 0 \leq x < 1}. - -The runtime-library implements George Marsaglia's KISS (Keep It Simple -Stupid) random number generator (RNG). This RNG combines: -@enumerate -@item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885} -with a period of @math{2^{32}}, -@item A 3-shift shift-register generator with a period of @math{2^{32} - 1}, -@item Two 16-bit multiply-with-carry generators with a period of -@math{597273182964842497 > 2^{59}}. -@end enumerate -The overall period exceeds @math{2^{123}}. - -Please note, this RNG is thread safe if used within OpenMP directives, -i.e., its state will be consistent while called from multiple threads. -However, the KISS generator does not create random numbers in parallel -from multiple sources, but in sequence from a single source. If an -OpenMP-enabled application heavily relies on random numbers, one should -consider employing a dedicated parallel random number generator instead. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{RANDOM_NUMBER(HARVEST)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. -@end multitable - -@item @emph{Example}: -@smallexample -program test_random_number - REAL :: r(5,5) - CALL init_random_seed() ! see example of RANDOM_SEED - CALL RANDOM_NUMBER(r) -end program -@end smallexample - -@item @emph{See also}: -@ref{RANDOM_SEED} -@end table - - - -@node RANDOM_SEED -@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence -@fnindex RANDOM_SEED -@cindex random number generation, seeding -@cindex seeding a random number generator - -@table @asis -@item @emph{Description}: -Restarts or queries the state of the pseudorandom number generator used by -@code{RANDOM_NUMBER}. - -If @code{RANDOM_SEED} is called without arguments, it is initialized -to a default state. The example below shows how to initialize the -random seed with a varying seed in order to ensure a different random -number sequence for each invocation of the program. Note that setting -any of the seed values to zero should be avoided as it can result in -poor quality random numbers being generated. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL RANDOM_SEED([SIZE, PUT, GET])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default -@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size -of the arrays used with the @var{PUT} and @var{GET} arguments. -@item @var{PUT} @tab (Optional) Shall be an array of type default -@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of -the array must be larger than or equal to the number returned by the -@var{SIZE} argument. -@item @var{GET} @tab (Optional) Shall be an array of type default -@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size -of the array must be larger than or equal to the number returned by -the @var{SIZE} argument. -@end multitable - -@item @emph{Example}: -@smallexample -subroutine init_random_seed() - implicit none - integer, allocatable :: seed(:) - integer :: i, n, un, istat, dt(8), pid, t(2), s - integer(8) :: count, tms - - call random_seed(size = n) - allocate(seed(n)) - ! First try if the OS provides a random number generator - open(newunit=un, file="/dev/urandom", access="stream", & - form="unformatted", action="read", status="old", iostat=istat) - if (istat == 0) then - read(un) seed - close(un) - else - ! Fallback to XOR:ing the current time and pid. The PID is - ! useful in case one launches multiple instances of the same - ! program in parallel. - call system_clock(count) - if (count /= 0) then - t = transfer(count, t) - else - call date_and_time(values=dt) - tms = (dt(1) - 1970) * 365_8 * 24 * 60 * 60 * 1000 & - + dt(2) * 31_8 * 24 * 60 * 60 * 1000 & - + dt(3) * 24 * 60 * 60 * 60 * 1000 & - + dt(5) * 60 * 60 * 1000 & - + dt(6) * 60 * 1000 + dt(7) * 1000 & - + dt(8) - t = transfer(tms, t) - end if - s = ieor(t(1), t(2)) - pid = getpid() + 1099279 ! Add a prime - s = ieor(s, pid) - if (n >= 3) then - seed(1) = t(1) + 36269 - seed(2) = t(2) + 72551 - seed(3) = pid - if (n > 3) then - seed(4:) = s + 37 * (/ (i, i = 0, n - 4) /) - end if - else - seed = s + 37 * (/ (i, i = 0, n - 1 ) /) - end if - end if - call random_seed(put=seed) -end subroutine init_random_seed -@end smallexample - -@item @emph{See also}: -@ref{RANDOM_NUMBER} -@end table - - - -@node RANGE -@section @code{RANGE} --- Decimal exponent range -@fnindex RANGE -@cindex model representation, range - -@table @asis -@item @emph{Description}: -@code{RANGE(X)} returns the decimal exponent range in the model of the -type of @code{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = RANGE(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} -or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. - -@item @emph{See also}: -@ref{SELECTED_REAL_KIND}, @ref{PRECISION} - -@item @emph{Example}: -See @code{PRECISION} for an example. -@end table - - - -@node RANK -@section @code{RANK} --- Rank of a data object -@fnindex RANK -@cindex rank - -@table @asis -@item @emph{Description}: -@code{RANK(A)} returns the rank of a scalar or array data object. - -@item @emph{Standard}: -Technical Specification (TS) 29113 - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = RANGE(A)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab can be of any type -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the default integer -kind. For arrays, their rank is returned; for scalars zero is returned. - -@item @emph{Example}: -@smallexample -program test_rank - integer :: a - real, allocatable :: b(:,:) - - print *, rank(a), rank(b) ! Prints: 0 3 -end program test_rank -@end smallexample - -@end table - - - -@node REAL -@section @code{REAL} --- Convert to real type -@fnindex REAL -@fnindex REALPART -@fnindex FLOAT -@fnindex DFLOAT -@fnindex SNGL -@cindex conversion, to real -@cindex complex numbers, real part - -@table @asis -@item @emph{Description}: -@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The -@code{REALPART} function is provided for compatibility with @command{g77}, -and its use is strongly discouraged. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = REAL(A [, KIND])} -@item @code{RESULT = REALPART(Z)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or -@code{COMPLEX}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -These functions return a @code{REAL} variable or array under -the following rules: - -@table @asis -@item (A) -@code{REAL(A)} is converted to a default real type if @var{A} is an -integer or real variable. -@item (B) -@code{REAL(A)} is converted to a real type with the kind type parameter -of @var{A} if @var{A} is a complex variable. -@item (C) -@code{REAL(A, KIND)} is converted to a real type with kind type -parameter @var{KIND} if @var{A} is a complex, integer, or real -variable. -@end table - -@item @emph{Example}: -@smallexample -program test_real - complex :: x = (1.0, 2.0) - print *, real(x), real(x,8), realpart(x) -end program test_real -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later -@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension -@item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later -@end multitable - - -@item @emph{See also}: -@ref{DBLE} - -@end table - - - -@node RENAME -@section @code{RENAME} --- Rename a file -@fnindex RENAME -@cindex file system, rename file - -@table @asis -@item @emph{Description}: -Renames a file from file @var{PATH1} to @var{PATH2}. A null -character (@code{CHAR(0)}) can be used to mark the end of the names in -@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file -names are ignored. If the @var{STATUS} argument is supplied, it -contains 0 on success or a nonzero error code upon return; see -@code{rename(2)}. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} -@item @code{STATUS = RENAME(PATH1, PATH2)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. -@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. -@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. -@end multitable - -@item @emph{See also}: -@ref{LINK} - -@end table - - - -@node REPEAT -@section @code{REPEAT} --- Repeated string concatenation -@fnindex REPEAT -@cindex string, repeat -@cindex string, concatenate - -@table @asis -@item @emph{Description}: -Concatenates @var{NCOPIES} copies of a string. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = REPEAT(STRING, NCOPIES)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. -@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies -of @var{STRING}. - -@item @emph{Example}: -@smallexample -program test_repeat - write(*,*) repeat("x", 5) ! "xxxxx" -end program -@end smallexample -@end table - - - -@node RESHAPE -@section @code{RESHAPE} --- Function to reshape an array -@fnindex RESHAPE -@cindex array, change dimensions -@cindex array, transmogrify - -@table @asis -@item @emph{Description}: -Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, -the new array may be padded with elements from @var{PAD} or permuted -as defined by @var{ORDER}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SOURCE} @tab Shall be an array of any type. -@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an -array of rank one. Its values must be positive or zero. -@item @var{PAD} @tab (Optional) shall be an array of the same -type as @var{SOURCE}. -@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} -and an array of the same shape as @var{SHAPE}. Its values shall -be a permutation of the numbers from 1 to n, where n is the size of -@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall -be assumed. -@end multitable - -@item @emph{Return value}: -The result is an array of shape @var{SHAPE} with the same type as -@var{SOURCE}. - -@item @emph{Example}: -@smallexample -PROGRAM test_reshape - INTEGER, DIMENSION(4) :: x - WRITE(*,*) SHAPE(x) ! prints "4" - WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{SHAPE} -@end table - - - -@node RRSPACING -@section @code{RRSPACING} --- Reciprocal of the relative spacing -@fnindex RRSPACING -@cindex real number, relative spacing -@cindex floating point, relative spacing - - -@table @asis -@item @emph{Description}: -@code{RRSPACING(X)} returns the reciprocal of the relative spacing of -model numbers near @var{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = RRSPACING(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. -The value returned is equal to -@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. - -@item @emph{See also}: -@ref{SPACING} -@end table - - - -@node RSHIFT -@section @code{RSHIFT} --- Right shift bits -@fnindex RSHIFT -@cindex bits, shift right - -@table @asis -@item @emph{Description}: -@code{RSHIFT} returns a value corresponding to @var{I} with all of the -bits shifted right by @var{SHIFT} places. If the absolute value of -@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. -Bits shifted out from the right end are lost. The fill is arithmetic: the -bits shifted in from the left end are equal to the leftmost bit, which in -two's complement representation is the sign bit. - -This function has been superseded by the @code{SHIFTA} intrinsic, which -is standard in Fortran 2008 and later. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = RSHIFT(I, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR}, -@ref{SHIFTL} - -@end table - - - -@node SAME_TYPE_AS -@section @code{SAME_TYPE_AS} --- Query dynamic types for equality -@fnindex SAME_TYPE_AS - -@table @asis -@item @emph{Description}: -Query dynamic types for equality. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = SAME_TYPE_AS(A, B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be an object of extensible declared type or -unlimited polymorphic. -@item @var{B} @tab Shall be an object of extensible declared type or -unlimited polymorphic. -@end multitable - -@item @emph{Return value}: -The return value is a scalar of type default logical. It is true if and -only if the dynamic type of A is the same as the dynamic type of B. - -@item @emph{See also}: -@ref{EXTENDS_TYPE_OF} - -@end table - - - -@node SCALE -@section @code{SCALE} --- Scale a real value -@fnindex SCALE -@cindex real number, scale -@cindex floating point, scale - -@table @asis -@item @emph{Description}: -@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SCALE(X, I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type of the argument shall be a @code{REAL}. -@item @var{I} @tab The type of the argument shall be a @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. -Its value is @code{X * RADIX(X)**I}. - -@item @emph{Example}: -@smallexample -program test_scale - real :: x = 178.1387e-4 - integer :: i = 5 - print *, scale(x,i), x*radix(x)**i -end program test_scale -@end smallexample - -@end table - - - -@node SCAN -@section @code{SCAN} --- Scan a string for the presence of a set of characters -@fnindex SCAN -@cindex string, find subset - -@table @asis -@item @emph{Description}: -Scans a @var{STRING} for any of the characters in a @var{SET} -of characters. - -If @var{BACK} is either absent or equals @code{FALSE}, this function -returns the position of the leftmost character of @var{STRING} that is -in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position -is returned. If no character of @var{SET} is found in @var{STRING}, the -result is zero. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be of type @code{CHARACTER}. -@item @var{SET} @tab Shall be of type @code{CHARACTER}. -@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - -@item @emph{Example}: -@smallexample -PROGRAM test_scan - WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' - WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' - WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{INDEX intrinsic}, @ref{VERIFY} -@end table - - - -@node SECNDS -@section @code{SECNDS} --- Time function -@fnindex SECNDS -@cindex time, elapsed -@cindex elapsed time - -@table @asis -@item @emph{Description}: -@code{SECNDS(X)} gets the time in seconds from the real-time system clock. -@var{X} is a reference time, also in seconds. If this is zero, the time in -seconds from midnight is returned. This function is non-standard and its -use is discouraged. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = SECNDS (X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{T} @tab Shall be of type @code{REAL(4)}. -@item @var{X} @tab Shall be of type @code{REAL(4)}. -@end multitable - -@item @emph{Return value}: -None - -@item @emph{Example}: -@smallexample -program test_secnds - integer :: i - real(4) :: t1, t2 - print *, secnds (0.0) ! seconds since midnight - t1 = secnds (0.0) ! reference time - do i = 1, 10000000 ! do something - end do - t2 = secnds (t1) ! elapsed time - print *, "Something took ", t2, " seconds." -end program test_secnds -@end smallexample -@end table - - - -@node SECOND -@section @code{SECOND} --- CPU time function -@fnindex SECOND -@cindex time, elapsed -@cindex elapsed time - -@table @asis -@item @emph{Description}: -Returns a @code{REAL(4)} value representing the elapsed CPU time in -seconds. This provides the same functionality as the standard -@code{CPU_TIME} intrinsic, and is only included for backwards -compatibility. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL SECOND(TIME)} -@item @code{TIME = SECOND()} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{TIME} @tab Shall be of type @code{REAL(4)}. -@end multitable - -@item @emph{Return value}: -In either syntax, @var{TIME} is set to the process's current runtime in -seconds. - -@item @emph{See also}: -@ref{CPU_TIME} - -@end table - - - -@node SELECTED_CHAR_KIND -@section @code{SELECTED_CHAR_KIND} --- Choose character kind -@fnindex SELECTED_CHAR_KIND -@cindex character kind -@cindex kind, character - -@table @asis -@item @emph{Description}: - -@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character -set named @var{NAME}, if a character set with such a name is supported, -or @math{-1} otherwise. Currently, supported character sets include -``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' -(Universal Character Set, UCS-4) which is commonly known as Unicode. - -@item @emph{Standard}: -Fortran 2003 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = SELECTED_CHAR_KIND(NAME)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NAME} @tab Shall be a scalar and of the default character type. -@end multitable - -@item @emph{Example}: -@smallexample -program character_kind - use iso_fortran_env - implicit none - integer, parameter :: ascii = selected_char_kind ("ascii") - integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') - - character(kind=ascii, len=26) :: alphabet - character(kind=ucs4, len=30) :: hello_world - - alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" - hello_world = ucs4_'Hello World and Ni Hao -- ' & - // char (int (z'4F60'), ucs4) & - // char (int (z'597D'), ucs4) - - write (*,*) alphabet - - open (output_unit, encoding='UTF-8') - write (*,*) trim (hello_world) -end program character_kind -@end smallexample -@end table - - - -@node SELECTED_INT_KIND -@section @code{SELECTED_INT_KIND} --- Choose integer kind -@fnindex SELECTED_INT_KIND -@cindex integer kind -@cindex kind, integer - -@table @asis -@item @emph{Description}: -@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer -type that can represent all values ranging from @math{-10^R} (exclusive) -to @math{10^R} (exclusive). If there is no integer kind that accommodates -this range, @code{SELECTED_INT_KIND} returns @math{-1}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = SELECTED_INT_KIND(R)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. -@end multitable - -@item @emph{Example}: -@smallexample -program large_integers - integer,parameter :: k5 = selected_int_kind(5) - integer,parameter :: k15 = selected_int_kind(15) - integer(kind=k5) :: i5 - integer(kind=k15) :: i15 - - print *, huge(i5), huge(i15) - - ! The following inequalities are always true - print *, huge(i5) >= 10_k5**5-1 - print *, huge(i15) >= 10_k15**15-1 -end program large_integers -@end smallexample -@end table - - - -@node SELECTED_REAL_KIND -@section @code{SELECTED_REAL_KIND} --- Choose real kind -@fnindex SELECTED_REAL_KIND -@cindex real kind -@cindex kind, real -@cindex radix, real - -@table @asis -@item @emph{Description}: -@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type -with decimal precision of at least @code{P} digits, exponent range of -at least @code{R}, and with a radix of @code{RADIX}. - -@item @emph{Standard}: -Fortran 95 and later, with @code{RADIX} Fortran 2008 or later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. -@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. -@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. -@end multitable -Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall -be present; since Fortran 2008, they are assumed to be zero if absent. - -@item @emph{Return value}: - -@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of -a real data type with decimal precision of at least @code{P} digits, a -decimal exponent range of at least @code{R}, and with the requested -@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with -any radix can be returned. If more than one real data type meet the -criteria, the kind of the data type with the smallest decimal precision -is returned. If no real data type matches the criteria, the result is -@table @asis -@item -1 if the processor does not support a real data type with a -precision greater than or equal to @code{P}, but the @code{R} and -@code{RADIX} requirements can be fulfilled -@item -2 if the processor does not support a real type with an exponent -range greater than or equal to @code{R}, but @code{P} and @code{RADIX} -are fulfillable -@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements -are fulfillable -@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements -are fulfillable -@item -5 if there is no real type with the given @code{RADIX} -@end table - -@item @emph{See also}: -@ref{PRECISION}, @ref{RANGE}, @ref{RADIX} - -@item @emph{Example}: -@smallexample -program real_kinds - integer,parameter :: p6 = selected_real_kind(6) - integer,parameter :: p10r100 = selected_real_kind(10,100) - integer,parameter :: r400 = selected_real_kind(r=400) - real(kind=p6) :: x - real(kind=p10r100) :: y - real(kind=r400) :: z - - print *, precision(x), range(x) - print *, precision(y), range(y) - print *, precision(z), range(z) -end program real_kinds -@end smallexample -@end table - - - -@node SET_EXPONENT -@section @code{SET_EXPONENT} --- Set the exponent of the model -@fnindex SET_EXPONENT -@cindex real number, set exponent -@cindex floating point, set exponent - -@table @asis -@item @emph{Description}: -@code{SET_EXPONENT(X, I)} returns the real number whose fractional part -is that that of @var{X} and whose exponent part is @var{I}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SET_EXPONENT(X, I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL}. -@item @var{I} @tab Shall be of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. -The real number whose fractional part -is that that of @var{X} and whose exponent part if @var{I} is returned; -it is @code{FRACTION(X) * RADIX(X)**I}. - -@item @emph{Example}: -@smallexample -PROGRAM test_setexp - REAL :: x = 178.1387e-4 - INTEGER :: i = 17 - PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i -END PROGRAM -@end smallexample - -@end table - - - -@node SHAPE -@section @code{SHAPE} --- Determine the shape of an array -@fnindex SHAPE -@cindex array, shape - -@table @asis -@item @emph{Description}: -Determines the shape of an array. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = SHAPE(SOURCE [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SOURCE} @tab Shall be an array or scalar of any type. -If @var{SOURCE} is a pointer it must be associated and allocatable -arrays must be allocated. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} -has dimensions. The elements of the resulting array correspond to the extend -of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, -the result is the rank one array of size zero. If @var{KIND} is absent, the -return value has the default integer kind otherwise the specified kind. - -@item @emph{Example}: -@smallexample -PROGRAM test_shape - INTEGER, DIMENSION(-1:1, -1:2) :: A - WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) - WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{RESHAPE}, @ref{SIZE} -@end table - - - -@node SHIFTA -@section @code{SHIFTA} --- Right shift with fill -@fnindex SHIFTA -@cindex bits, shift right -@cindex shift, right with fill - -@table @asis -@item @emph{Description}: -@code{SHIFTA} returns a value corresponding to @var{I} with all of the -bits shifted right by @var{SHIFT} places. If the absolute value of -@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. -Bits shifted out from the right end are lost. The fill is arithmetic: the -bits shifted in from the left end are equal to the leftmost bit, which in -two's complement representation is the sign bit. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SHIFTA(I, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{SHIFTL}, @ref{SHIFTR} -@end table - - - -@node SHIFTL -@section @code{SHIFTL} --- Left shift -@fnindex SHIFTL -@cindex bits, shift left -@cindex shift, left - -@table @asis -@item @emph{Description}: -@code{SHIFTL} returns a value corresponding to @var{I} with all of the -bits shifted left by @var{SHIFT} places. If the absolute value of -@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. -Bits shifted out from the left end are lost, and bits shifted in from -the right end are set to 0. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SHIFTL(I, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{SHIFTA}, @ref{SHIFTR} -@end table - - - -@node SHIFTR -@section @code{SHIFTR} --- Right shift -@fnindex SHIFTR -@cindex bits, shift right -@cindex shift, right - -@table @asis -@item @emph{Description}: -@code{SHIFTR} returns a value corresponding to @var{I} with all of the -bits shifted right by @var{SHIFT} places. If the absolute value of -@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. -Bits shifted out from the right end are lost, and bits shifted in from -the left end are set to 0. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SHIFTR(I, SHIFT)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be @code{INTEGER}. -@item @var{SHIFT} @tab The type shall be @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of the same kind as -@var{I}. - -@item @emph{See also}: -@ref{SHIFTA}, @ref{SHIFTL} -@end table - - - -@node SIGN -@section @code{SIGN} --- Sign copying function -@fnindex SIGN -@fnindex ISIGN -@fnindex DSIGN -@cindex sign copying - -@table @asis -@item @emph{Description}: -@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SIGN(A, B)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} -@item @var{B} @tab Shall be of the same type and kind as @var{A} -@end multitable - -@item @emph{Return value}: -The kind of the return value is that of @var{A} and @var{B}. -If @math{B\ge 0} then the result is @code{ABS(A)}, else -it is @code{-ABS(A)}. - -@item @emph{Example}: -@smallexample -program test_sign - print *, sign(-12,1) - print *, sign(-12,0) - print *, sign(-12,-1) - - print *, sign(-12.,1.) - print *, sign(-12.,0.) - print *, sign(-12.,-1.) -end program test_sign -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Arguments @tab Return type @tab Standard -@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu -@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu -@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu -@end multitable -@end table - - - -@node SIGNAL -@section @code{SIGNAL} --- Signal handling subroutine (or function) -@fnindex SIGNAL -@cindex system, signal handling - -@table @asis -@item @emph{Description}: -@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine -@var{HANDLER} to be executed with a single integer argument when signal -@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to -turn off handling of signal @var{NUMBER} or revert to its default -action. See @code{signal(2)}. - -If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument -is supplied, it is set to the value returned by @code{signal(2)}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} -@item @code{STATUS = SIGNAL(NUMBER, HANDLER)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} -@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or -@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. -@code{INTEGER}. It is @code{INTENT(IN)}. -@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar -integer. It has @code{INTENT(OUT)}. -@end multitable -@c TODO: What should the interface of the handler be? Does it take arguments? - -@item @emph{Return value}: -The @code{SIGNAL} function returns the value returned by @code{signal(2)}. - -@item @emph{Example}: -@smallexample -program test_signal - intrinsic signal - external handler_print - - call signal (12, handler_print) - call signal (10, 1) - - call sleep (30) -end program test_signal -@end smallexample -@end table - - - -@node SIN -@section @code{SIN} --- Sine function -@fnindex SIN -@fnindex DSIN -@fnindex CSIN -@fnindex ZSIN -@fnindex CDSIN -@cindex trigonometric function, sine -@cindex sine - -@table @asis -@item @emph{Description}: -@code{SIN(X)} computes the sine of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SIN(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or -@code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has same type and kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_sin - real :: x = 0.0 - x = sin(x) -end program test_sin -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu -@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu -@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu -@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu -@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu -@end multitable - -@item @emph{See also}: -@ref{ASIN} -@end table - - - -@node SINH -@section @code{SINH} --- Hyperbolic sine function -@fnindex SINH -@fnindex DSINH -@cindex hyperbolic sine -@cindex hyperbolic function, sine -@cindex sine, hyperbolic - -@table @asis -@item @emph{Description}: -@code{SINH(X)} computes the hyperbolic sine of @var{X}. - -@item @emph{Standard}: -Fortran 95 and later, for a complex argument Fortran 2008 or later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SINH(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has same type and kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_sinh - real(8) :: x = - 1.0_8 - x = sinh(x) -end program test_sinh -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later -@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later -@end multitable - -@item @emph{See also}: -@ref{ASINH} -@end table - - - -@node SIZE -@section @code{SIZE} --- Determine the size of an array -@fnindex SIZE -@cindex array, size -@cindex array, number of elements -@cindex array, count elements - -@table @asis -@item @emph{Description}: -Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, -or the total number of elements in @var{ARRAY} if @var{DIM} is absent. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is -a pointer it must be associated and allocatable arrays must be allocated. -@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} -and its value shall be in the range from 1 to n, where n equals the rank -of @var{ARRAY}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - -@item @emph{Example}: -@smallexample -PROGRAM test_size - WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{SHAPE}, @ref{RESHAPE} -@end table - - -@node SIZEOF -@section @code{SIZEOF} --- Size in bytes of an expression -@fnindex SIZEOF -@cindex expression size -@cindex size of an expression - -@table @asis -@item @emph{Description}: -@code{SIZEOF(X)} calculates the number of bytes of storage the -expression @code{X} occupies. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Intrinsic function - -@item @emph{Syntax}: -@code{N = SIZEOF(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The argument shall be of any type, rank or shape. -@end multitable - -@item @emph{Return value}: -The return value is of type integer and of the system-dependent kind -@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the -number of bytes occupied by the argument. If the argument has the -@code{POINTER} attribute, the number of bytes of the storage area pointed -to is returned. If the argument is of a derived type with @code{POINTER} -or @code{ALLOCATABLE} components, the return value does not account for -the sizes of the data pointed to by these components. If the argument is -polymorphic, the size according to the declared type is returned. The argument -may not be a procedure or procedure pointer. - -@item @emph{Example}: -@smallexample - integer :: i - real :: r, s(5) - print *, (sizeof(s)/sizeof(r) == 5) - end -@end smallexample -The example will print @code{.TRUE.} unless you are using a platform -where default @code{REAL} variables are unusually padded. - -@item @emph{See also}: -@ref{C_SIZEOF}, @ref{STORAGE_SIZE} -@end table - - -@node SLEEP -@section @code{SLEEP} --- Sleep for the specified number of seconds -@fnindex SLEEP -@cindex delayed execution - -@table @asis -@item @emph{Description}: -Calling this subroutine causes the process to pause for @var{SECONDS} seconds. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL SLEEP(SECONDS)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. -@end multitable - -@item @emph{Example}: -@smallexample -program test_sleep - call sleep(5) -end -@end smallexample -@end table - - - -@node SPACING -@section @code{SPACING} --- Smallest distance between two numbers of a given type -@fnindex SPACING -@cindex real number, relative spacing -@cindex floating point, relative spacing - -@table @asis -@item @emph{Description}: -Determines the distance between the argument @var{X} and the nearest -adjacent number of the same type. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SPACING(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as the input argument @var{X}. - -@item @emph{Example}: -@smallexample -PROGRAM test_spacing - INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) - INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) - - WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 - WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{RRSPACING} -@end table - - - -@node SPREAD -@section @code{SPREAD} --- Add a dimension to an array -@fnindex SPREAD -@cindex array, increase dimension -@cindex array, duplicate elements -@cindex array, duplicate dimensions - -@table @asis -@item @emph{Description}: -Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified -dimension @var{DIM}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SOURCE} @tab Shall be a scalar or an array of any type and -a rank less than seven. -@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a -value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. -@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The result is an array of the same type as @var{SOURCE} and has rank n+1 -where n equals the rank of @var{SOURCE}. - -@item @emph{Example}: -@smallexample -PROGRAM test_spread - INTEGER :: a = 1, b(2) = (/ 1, 2 /) - WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" - WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{UNPACK} -@end table - - - -@node SQRT -@section @code{SQRT} --- Square-root function -@fnindex SQRT -@fnindex DSQRT -@fnindex CSQRT -@fnindex ZSQRT -@fnindex CDSQRT -@cindex root -@cindex square-root - -@table @asis -@item @emph{Description}: -@code{SQRT(X)} computes the square root of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = SQRT(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or -@code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{REAL} or @code{COMPLEX}. -The kind type parameter is the same as @var{X}. - -@item @emph{Example}: -@smallexample -program test_sqrt - real(8) :: x = 2.0_8 - complex :: z = (1.0, 2.0) - x = sqrt(x) - z = sqrt(z) -end program test_sqrt -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later -@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later -@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later -@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension -@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension -@end multitable -@end table - - - -@node SRAND -@section @code{SRAND} --- Reinitialize the random number generator -@fnindex SRAND -@cindex random number generation, seeding -@cindex seeding a random number generator - -@table @asis -@item @emph{Description}: -@code{SRAND} reinitializes the pseudo-random number generator -called by @code{RAND} and @code{IRAND}. The new seed used by the -generator is specified by the required argument @var{SEED}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL SRAND(SEED)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. -@end multitable - -@item @emph{Return value}: -Does not return anything. - -@item @emph{Example}: -See @code{RAND} and @code{IRAND} for examples. - -@item @emph{Notes}: -The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to -initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER} -to generate pseudo-random numbers. Please note that in -GNU Fortran, these two sets of intrinsics (@code{RAND}, -@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and -@code{RANDOM_SEED} on the other hand) access two independent -pseudo-random number generators. - -@item @emph{See also}: -@ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER} - -@end table - - - -@node STAT -@section @code{STAT} --- Get file status -@fnindex STAT -@cindex file system, file status - -@table @asis -@item @emph{Description}: -This function returns information about a file. No permissions are required on -the file itself, but execute (search) permission is required on all of the -directories in path that lead to the file. - -The elements that are obtained and stored in the array @code{VALUES}: -@multitable @columnfractions .15 .70 -@item @code{VALUES(1)} @tab Device ID -@item @code{VALUES(2)} @tab Inode number -@item @code{VALUES(3)} @tab File mode -@item @code{VALUES(4)} @tab Number of links -@item @code{VALUES(5)} @tab Owner's uid -@item @code{VALUES(6)} @tab Owner's gid -@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) -@item @code{VALUES(8)} @tab File size (bytes) -@item @code{VALUES(9)} @tab Last access time -@item @code{VALUES(10)} @tab Last modification time -@item @code{VALUES(11)} @tab Last file status change time -@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) -@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) -@end multitable - -Not all these elements are relevant on all systems. -If an element is not relevant, it is returned as 0. - -This intrinsic is provided in both subroutine and function forms; however, -only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL STAT(NAME, VALUES [, STATUS])} -@item @code{STATUS = STAT(NAME, VALUES)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the -default kind and a valid path within the file system. -@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 -on success and a system specific error code otherwise. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_stat - INTEGER, DIMENSION(13) :: buff - INTEGER :: status - - CALL STAT("/etc/passwd", buff, status) - - IF (status == 0) THEN - WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) - WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) - WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) - WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) - WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) - WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) - WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) - WRITE (*, FMT="('File size:', T30, I19)") buff(8) - WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) - WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) - WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) - WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) - WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) - END IF -END PROGRAM -@end smallexample - -@item @emph{See also}: -To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT} -@end table - - - -@node STORAGE_SIZE -@section @code{STORAGE_SIZE} --- Storage size in bits -@fnindex STORAGE_SIZE -@cindex storage size - -@table @asis -@item @emph{Description}: -Returns the storage size of argument @var{A} in bits. -@item @emph{Standard}: -Fortran 2008 and later -@item @emph{Class}: -Inquiry function -@item @emph{Syntax}: -@code{RESULT = STORAGE_SIZE(A [, KIND])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{A} @tab Shall be a scalar or array of any type. -@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. -@end multitable - -@item @emph{Return Value}: -The result is a scalar integer with the kind type parameter specified by KIND -(or default integer type if KIND is missing). The result value is the size -expressed in bits for an element of an array that has the dynamic type and type -parameters of A. - -@item @emph{See also}: -@ref{C_SIZEOF}, @ref{SIZEOF} -@end table - - - -@node SUM -@section @code{SUM} --- Sum of array elements -@fnindex SUM -@cindex array, sum -@cindex array, add elements -@cindex array, conditionally add elements -@cindex sum array elements - -@table @asis -@item @emph{Description}: -Adds the elements of @var{ARRAY} along dimension @var{DIM} if -the corresponding element in @var{MASK} is @code{TRUE}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = SUM(ARRAY[, MASK])} -@item @code{RESULT = SUM(ARRAY, DIM[, MASK])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, -@code{REAL} or @code{COMPLEX}. -@item @var{DIM} @tab (Optional) shall be a scalar of type -@code{INTEGER} with a value in the range from 1 to n, where n -equals the rank of @var{ARRAY}. -@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} -and either be a scalar or an array of the same shape as @var{ARRAY}. -@end multitable - -@item @emph{Return value}: -The result is of the same type as @var{ARRAY}. - -If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} -is returned. Otherwise, an array of rank n-1, where n equals the rank of -@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} -dropped is returned. - -@item @emph{Example}: -@smallexample -PROGRAM test_sum - INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) - print *, SUM(x) ! all elements, sum = 15 - print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{PRODUCT} -@end table - - - -@node SYMLNK -@section @code{SYMLNK} --- Create a symbolic link -@fnindex SYMLNK -@cindex file system, create link -@cindex file system, soft link - -@table @asis -@item @emph{Description}: -Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null -character (@code{CHAR(0)}) can be used to mark the end of the names in -@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file -names are ignored. If the @var{STATUS} argument is supplied, it -contains 0 on success or a nonzero error code upon return; see -@code{symlink(2)}. If the system does not supply @code{symlink(2)}, -@code{ENOSYS} is returned. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])} -@item @code{STATUS = SYMLNK(PATH1, PATH2)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. -@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. -@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. -@end multitable - -@item @emph{See also}: -@ref{LINK}, @ref{UNLINK} - -@end table - - - -@node SYSTEM -@section @code{SYSTEM} --- Execute a shell command -@fnindex SYSTEM -@cindex system, system call - -@table @asis -@item @emph{Description}: -Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If -argument @var{STATUS} is present, it contains the value returned by -@code{system(3)}, which is presumably 0 if the shell command succeeded. -Note that which shell is used to invoke the command is system-dependent -and environment-dependent. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -Note that the @code{system} function need not be thread-safe. It is -the responsibility of the user to ensure that @code{system} is not -called concurrently. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL SYSTEM(COMMAND [, STATUS])} -@item @code{STATUS = SYSTEM(COMMAND)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. -@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. -@end multitable - -@item @emph{See also}: -@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard -and should considered in new code for future portability. -@end table - - - -@node SYSTEM_CLOCK -@section @code{SYSTEM_CLOCK} --- Time function -@fnindex SYSTEM_CLOCK -@cindex time, clock ticks -@cindex clock ticks - -@table @asis -@item @emph{Description}: -Determines the @var{COUNT} of a processor clock since an unspecified -time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines -the number of clock ticks per second. If the platform supports a high -resolution monotonic clock, that clock is used and can provide up to -nanosecond resolution. If a high resolution monotonic clock is not -available, the implementation falls back to a potentially lower -resolution realtime clock. - -@var{COUNT_RATE} is system dependent and can vary depending on the kind of the -arguments. For @var{kind=4} arguments, @var{COUNT} usually represents -milliseconds, while for @var{kind=8} arguments, @var{COUNT} typically -represents micro- or nanoseconds. @var{COUNT_MAX} usually equals -@code{HUGE(COUNT_MAX)}. - -If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and -@var{COUNT_RATE} and @var{COUNT_MAX} are set to zero. - -When running on a platform using the GNU C library (glibc), or a -derivative thereof, the high resolution monotonic clock is available -only when linking with the @var{rt} library. This can be done -explicitly by adding the @code{-lrt} flag when linking the -application, but is also done implicitly when using OpenMP. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Subroutine - -@item @emph{Syntax}: -@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{COUNT} @tab (Optional) shall be a scalar of type -@code{INTEGER} with @code{INTENT(OUT)}. -@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type -@code{INTEGER} with @code{INTENT(OUT)}. -@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type -@code{INTEGER} with @code{INTENT(OUT)}. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_system_clock - INTEGER :: count, count_rate, count_max - CALL SYSTEM_CLOCK(count, count_rate, count_max) - WRITE(*,*) count, count_rate, count_max -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{DATE_AND_TIME}, @ref{CPU_TIME} -@end table - - - -@node TAN -@section @code{TAN} --- Tangent function -@fnindex TAN -@fnindex DTAN -@cindex trigonometric function, tangent -@cindex tangent - -@table @asis -@item @emph{Description}: -@code{TAN(X)} computes the tangent of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later, for a complex argument Fortran 2008 or later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = TAN(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has same type and kind as @var{X}. - -@item @emph{Example}: -@smallexample -program test_tan - real(8) :: x = 0.165_8 - x = tan(x) -end program test_tan -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later -@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later -@end multitable - -@item @emph{See also}: -@ref{ATAN} -@end table - - - -@node TANH -@section @code{TANH} --- Hyperbolic tangent function -@fnindex TANH -@fnindex DTANH -@cindex hyperbolic tangent -@cindex hyperbolic function, tangent -@cindex tangent, hyperbolic - -@table @asis -@item @emph{Description}: -@code{TANH(X)} computes the hyperbolic tangent of @var{X}. - -@item @emph{Standard}: -Fortran 77 and later, for a complex argument Fortran 2008 or later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{X = TANH(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. -@end multitable - -@item @emph{Return value}: -The return value has same type and kind as @var{X}. If @var{X} is -complex, the imaginary part of the result is in radians. If @var{X} -is @code{REAL}, the return value lies in the range -@math{ - 1 \leq tanh(x) \leq 1 }. - -@item @emph{Example}: -@smallexample -program test_tanh - real(8) :: x = 2.1_8 - x = tanh(x) -end program test_tanh -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .20 .20 .20 .25 -@item Name @tab Argument @tab Return type @tab Standard -@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later -@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later -@end multitable - -@item @emph{See also}: -@ref{ATANH} -@end table - - - -@node THIS_IMAGE -@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image -@fnindex THIS_IMAGE -@cindex coarray, @code{THIS_IMAGE} -@cindex images, index of this image - -@table @asis -@item @emph{Description}: -Returns the cosubscript for this image. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{RESULT = THIS_IMAGE()} -@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} -present, required). -@item @var{DIM} @tab default integer scalar (optional). If present, -@var{DIM} shall be between one and the corank of @var{COARRAY}. -@end multitable - - -@item @emph{Return value}: -Default integer. If @var{COARRAY} is not present, it is scalar and its value -is the index of the invoking image. Otherwise, if @var{DIM} is not present, -a rank-1 array with corank elements is returned, containing the cosubscripts -for @var{COARRAY} specifying the invoking image. If @var{DIM} is present, -a scalar is returned, with the value of the @var{DIM} element of -@code{THIS_IMAGE(COARRAY)}. - -@item @emph{Example}: -@smallexample -INTEGER :: value[*] -INTEGER :: i -value = THIS_IMAGE() -SYNC ALL -IF (THIS_IMAGE() == 1) THEN - DO i = 1, NUM_IMAGES() - WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] - END DO -END IF -@end smallexample - -@item @emph{See also}: -@ref{NUM_IMAGES}, @ref{IMAGE_INDEX} -@end table - - - -@node TIME -@section @code{TIME} --- Time function -@fnindex TIME -@cindex time, current -@cindex current time - -@table @asis -@item @emph{Description}: -Returns the current time encoded as an integer (in the manner of the -function @code{time(3)} in the C standard library). This value is -suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. - -This intrinsic is not fully portable, such as to systems with 32-bit -@code{INTEGER} types but supporting times wider than 32 bits. Therefore, -the values returned by this intrinsic might be, or become, negative, or -numerically less than previous values, during a single run of the -compiled program. - -See @ref{TIME8}, for information on a similar intrinsic that might be -portable to more GNU Fortran implementations, though to fewer Fortran -compilers. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = TIME()} - -@item @emph{Return value}: -The return value is a scalar of type @code{INTEGER(4)}. - -@item @emph{See also}: -@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} - -@end table - - - -@node TIME8 -@section @code{TIME8} --- Time function (64-bit) -@fnindex TIME8 -@cindex time, current -@cindex current time - -@table @asis -@item @emph{Description}: -Returns the current time encoded as an integer (in the manner of the -function @code{time(3)} in the C standard library). This value is -suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. - -@emph{Warning:} this intrinsic does not increase the range of the timing -values over that returned by @code{time(3)}. On a system with a 32-bit -@code{time(3)}, @code{TIME8} will return a 32-bit value, even though -it is converted to a 64-bit @code{INTEGER(8)} value. That means -overflows of the 32-bit value can still occur. Therefore, the values -returned by this intrinsic might be or become negative or numerically -less than previous values during a single run of the compiled program. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = TIME8()} - -@item @emph{Return value}: -The return value is a scalar of type @code{INTEGER(8)}. - -@item @emph{See also}: -@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME} - -@end table - - - -@node TINY -@section @code{TINY} --- Smallest positive number of a real kind -@fnindex TINY -@cindex limits, smallest number -@cindex model representation, smallest number - -@table @asis -@item @emph{Description}: -@code{TINY(X)} returns the smallest positive (non zero) number -in the model of the type of @code{X}. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = TINY(X)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab Shall be of type @code{REAL}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X} - -@item @emph{Example}: -See @code{HUGE} for an example. -@end table - - - -@node TRAILZ -@section @code{TRAILZ} --- Number of trailing zero bits of an integer -@fnindex TRAILZ -@cindex zero bits - -@table @asis -@item @emph{Description}: -@code{TRAILZ} returns the number of trailing zero bits of an integer. - -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = TRAILZ(I)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab Shall be of type @code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The type of the return value is the default @code{INTEGER}. -If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. - -@item @emph{Example}: -@smallexample -PROGRAM test_trailz - WRITE (*,*) TRAILZ(8) ! prints 3 -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT} -@end table - - - -@node TRANSFER -@section @code{TRANSFER} --- Transfer bit patterns -@fnindex TRANSFER -@cindex bits, move -@cindex type cast - -@table @asis -@item @emph{Description}: -Interprets the bitwise representation of @var{SOURCE} in memory as if it -is the representation of a variable or array of the same type and type -parameters as @var{MOLD}. - -This is approximately equivalent to the C concept of @emph{casting} one -type to another. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{SOURCE} @tab Shall be a scalar or an array of any type. -@item @var{MOLD} @tab Shall be a scalar or an array of any type. -@item @var{SIZE} @tab (Optional) shall be a scalar of type -@code{INTEGER}. -@end multitable - -@item @emph{Return value}: -The result has the same type as @var{MOLD}, with the bit level -representation of @var{SOURCE}. If @var{SIZE} is present, the result is -a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent -but @var{MOLD} is an array (of any size or shape), the result is a one- -dimensional array of the minimum length needed to contain the entirety -of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent -and @var{MOLD} is a scalar, the result is a scalar. - -If the bitwise representation of the result is longer than that of -@var{SOURCE}, then the leading bits of the result correspond to those of -@var{SOURCE} and any trailing bits are filled arbitrarily. - -When the resulting bit representation does not correspond to a valid -representation of a variable of the same type as @var{MOLD}, the results -are undefined, and subsequent operations on the result cannot be -guaranteed to produce sensible behavior. For example, it is possible to -create @code{LOGICAL} variables for which @code{@var{VAR}} and -@code{.NOT.@var{VAR}} both appear to be true. - -@item @emph{Example}: -@smallexample -PROGRAM test_transfer - integer :: x = 2143289344 - print *, transfer(x, 1.0) ! prints "NaN" on i686 -END PROGRAM -@end smallexample -@end table - - - -@node TRANSPOSE -@section @code{TRANSPOSE} --- Transpose an array of rank two -@fnindex TRANSPOSE -@cindex array, transpose -@cindex matrix, transpose -@cindex transpose - -@table @asis -@item @emph{Description}: -Transpose an array of rank two. Element (i, j) of the result has the value -@code{MATRIX(j, i)}, for all i, j. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = TRANSPOSE(MATRIX)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. -@end multitable - -@item @emph{Return value}: -The result has the same type as @var{MATRIX}, and has shape -@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. -@end table - - - -@node TRIM -@section @code{TRIM} --- Remove trailing blank characters of a string -@fnindex TRIM -@cindex string, remove trailing whitespace - -@table @asis -@item @emph{Description}: -Removes trailing blank characters of a string. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = TRIM(STRING)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. -@end multitable - -@item @emph{Return value}: -A scalar of type @code{CHARACTER} which length is that of @var{STRING} -less the number of trailing blanks. - -@item @emph{Example}: -@smallexample -PROGRAM test_trim - CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " - WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{ADJUSTL}, @ref{ADJUSTR} -@end table - - - -@node TTYNAM -@section @code{TTYNAM} --- Get the name of a terminal device. -@fnindex TTYNAM -@cindex system, terminal - -@table @asis -@item @emph{Description}: -Get the name of a terminal device. For more information, -see @code{ttyname(3)}. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL TTYNAM(UNIT, NAME)} -@item @code{NAME = TTYNAM(UNIT)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. -@item @var{NAME} @tab Shall be of type @code{CHARACTER}. -@end multitable - -@item @emph{Example}: -@smallexample -PROGRAM test_ttynam - INTEGER :: unit - DO unit = 1, 10 - IF (isatty(unit=unit)) write(*,*) ttynam(unit) - END DO -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{ISATTY} -@end table - - - -@node UBOUND -@section @code{UBOUND} --- Upper dimension bounds of an array -@fnindex UBOUND -@cindex array, upper bound - -@table @asis -@item @emph{Description}: -Returns the upper bounds of an array, or a single upper bound -along the @var{DIM} dimension. -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an array, of any type. -@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. -@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. -If @var{DIM} is absent, the result is an array of the upper bounds of -@var{ARRAY}. If @var{DIM} is present, the result is a scalar -corresponding to the upper bound of the array along that dimension. If -@var{ARRAY} is an expression rather than a whole array or array -structure component, or if it has a zero extent along the relevant -dimension, the upper bound is taken to be the number of elements along -the relevant dimension. - -@item @emph{See also}: -@ref{LBOUND}, @ref{LCOBOUND} -@end table - - - -@node UCOBOUND -@section @code{UCOBOUND} --- Upper codimension bounds of an array -@fnindex UCOBOUND -@cindex coarray, upper bound - -@table @asis -@item @emph{Description}: -Returns the upper cobounds of a coarray, or a single upper cobound -along the @var{DIM} codimension. -@item @emph{Standard}: -Fortran 2008 and later - -@item @emph{Class}: -Inquiry function - -@item @emph{Syntax}: -@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{ARRAY} @tab Shall be an coarray, of any type. -@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. -If @var{DIM} is absent, the result is an array of the lower cobounds of -@var{COARRAY}. If @var{DIM} is present, the result is a scalar -corresponding to the lower cobound of the array along that codimension. - -@item @emph{See also}: -@ref{LCOBOUND}, @ref{LBOUND} -@end table - - - -@node UMASK -@section @code{UMASK} --- Set the file creation mask -@fnindex UMASK -@cindex file system, file creation mask - -@table @asis -@item @emph{Description}: -Sets the file creation mask to @var{MASK}. If called as a function, it -returns the old value. If called as a subroutine and argument @var{OLD} -if it is supplied, it is set to the old value. See @code{umask(2)}. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL UMASK(MASK [, OLD])} -@item @code{OLD = UMASK(MASK)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. -@item @var{OLD} @tab (Optional) Shall be a scalar of type -@code{INTEGER}. -@end multitable - -@end table - - - -@node UNLINK -@section @code{UNLINK} --- Remove a file from the file system -@fnindex UNLINK -@cindex file system, remove file - -@table @asis -@item @emph{Description}: -Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be -used to mark the end of the name in @var{PATH}; otherwise, trailing -blanks in the file name are ignored. If the @var{STATUS} argument is -supplied, it contains 0 on success or a nonzero error code upon return; -see @code{unlink(2)}. - -This intrinsic is provided in both subroutine and function forms; -however, only one form can be used in any given program unit. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Subroutine, function - -@item @emph{Syntax}: -@multitable @columnfractions .80 -@item @code{CALL UNLINK(PATH [, STATUS])} -@item @code{STATUS = UNLINK(PATH)} -@end multitable - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{PATH} @tab Shall be of default @code{CHARACTER} type. -@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. -@end multitable - -@item @emph{See also}: -@ref{LINK}, @ref{SYMLNK} -@end table - - - -@node UNPACK -@section @code{UNPACK} --- Unpack an array of rank one into an array -@fnindex UNPACK -@cindex array, unpacking -@cindex array, increase dimension -@cindex array, scatter elements - -@table @asis -@item @emph{Description}: -Store the elements of @var{VECTOR} in an array of higher rank. - -@item @emph{Standard}: -Fortran 95 and later - -@item @emph{Class}: -Transformational function - -@item @emph{Syntax}: -@code{RESULT = UNPACK(VECTOR, MASK, FIELD)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{VECTOR} @tab Shall be an array of any type and rank one. It -shall have at least as many elements as @var{MASK} has @code{TRUE} values. -@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. -@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have -the same shape as @var{MASK}. -@end multitable - -@item @emph{Return value}: -The resulting array corresponds to @var{FIELD} with @code{TRUE} elements -of @var{MASK} replaced by values from @var{VECTOR} in array element order. - -@item @emph{Example}: -@smallexample -PROGRAM test_unpack - integer :: vector(2) = (/1,1/) - logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) - integer :: field(2,2) = 0, unity(2,2) - - ! result: unity matrix - unity = unpack(vector, reshape(mask, (/2,2/)), field) -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{PACK}, @ref{SPREAD} -@end table - - - -@node VERIFY -@section @code{VERIFY} --- Scan a string for characters not a given set -@fnindex VERIFY -@cindex string, find missing set - -@table @asis -@item @emph{Description}: -Verifies that all the characters in @var{STRING} belong to the set of -characters in @var{SET}. - -If @var{BACK} is either absent or equals @code{FALSE}, this function -returns the position of the leftmost character of @var{STRING} that is -not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost -position is returned. If all characters of @var{STRING} are found in -@var{SET}, the result is zero. - -@item @emph{Standard}: -Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later - -@item @emph{Class}: -Elemental function - -@item @emph{Syntax}: -@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{STRING} @tab Shall be of type @code{CHARACTER}. -@item @var{SET} @tab Shall be of type @code{CHARACTER}. -@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. -@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization -expression indicating the kind parameter of the result. -@end multitable - -@item @emph{Return value}: -The return value is of type @code{INTEGER} and of kind @var{KIND}. If -@var{KIND} is absent, the return value is of default integer kind. - -@item @emph{Example}: -@smallexample -PROGRAM test_verify - WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' - WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' - WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' - WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' - WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none -END PROGRAM -@end smallexample - -@item @emph{See also}: -@ref{SCAN}, @ref{INDEX intrinsic} -@end table - - - -@node XOR -@section @code{XOR} --- Bitwise logical exclusive OR -@fnindex XOR -@cindex bitwise logical exclusive or -@cindex logical exclusive or, bitwise - -@table @asis -@item @emph{Description}: -Bitwise logical exclusive or. - -This intrinsic routine is provided for backwards compatibility with -GNU Fortran 77. For integer arguments, programmers should consider -the use of the @ref{IEOR} intrinsic and for logical arguments the -@code{.NEQV.} operator, which are both defined by the Fortran standard. - -@item @emph{Standard}: -GNU extension - -@item @emph{Class}: -Function - -@item @emph{Syntax}: -@code{RESULT = XOR(I, J)} - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{I} @tab The type shall be either a scalar @code{INTEGER} -type or a scalar @code{LOGICAL} type. -@item @var{J} @tab The type shall be the same as the type of @var{I}. -@end multitable - -@item @emph{Return value}: -The return type is either a scalar @code{INTEGER} or a scalar -@code{LOGICAL}. If the kind type parameters differ, then the -smaller kind type is implicitly converted to larger kind, and the -return has the larger kind. - -@item @emph{Example}: -@smallexample -PROGRAM test_xor - LOGICAL :: T = .TRUE., F = .FALSE. - INTEGER :: a, b - DATA a / Z'F' /, b / Z'3' / - - WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) - WRITE (*,*) XOR(a, b) -END PROGRAM -@end smallexample - -@item @emph{See also}: -Fortran 95 elemental function: @ref{IEOR} -@end table - - - -@node Intrinsic Modules -@chapter Intrinsic Modules -@cindex intrinsic Modules - -@menu -* ISO_FORTRAN_ENV:: -* ISO_C_BINDING:: -* OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: -@end menu - -@node ISO_FORTRAN_ENV -@section @code{ISO_FORTRAN_ENV} -@table @asis -@item @emph{Standard}: -Fortran 2003 and later, except when otherwise noted -@end table - -The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer -named constants: - -@table @asis -@item @code{ATOMIC_INT_KIND}: -Default-kind integer constant to be used as kind parameter when defining -integer variables used in atomic operations. (Fortran 2008 or later.) - -@item @code{ATOMIC_LOGICAL_KIND}: -Default-kind integer constant to be used as kind parameter when defining -logical variables used in atomic operations. (Fortran 2008 or later.) - -@item @code{CHARACTER_KINDS}: -Default-kind integer constant array of rank one containing the supported kind -parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) - -@item @code{CHARACTER_STORAGE_SIZE}: -Size in bits of the character storage unit. - -@item @code{ERROR_UNIT}: -Identifies the preconnected unit used for error reporting. - -@item @code{FILE_STORAGE_SIZE}: -Size in bits of the file-storage unit. - -@item @code{INPUT_UNIT}: -Identifies the preconnected unit identified by the asterisk -(@code{*}) in @code{READ} statement. - -@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: -Kind type parameters to specify an INTEGER type with a storage -size of 16, 32, and 64 bits. It is negative if a target platform -does not support the particular kind. (Fortran 2008 or later.) - -@item @code{INTEGER_KINDS}: -Default-kind integer constant array of rank one containing the supported kind -parameters of the @code{INTEGER} type. (Fortran 2008 or later.) - -@item @code{IOSTAT_END}: -The value assigned to the variable passed to the @code{IOSTAT=} specifier of -an input/output statement if an end-of-file condition occurred. - -@item @code{IOSTAT_EOR}: -The value assigned to the variable passed to the @code{IOSTAT=} specifier of -an input/output statement if an end-of-record condition occurred. - -@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: -Scalar default-integer constant, used by @code{INQUIRE} for the -@code{IOSTAT=} specifier to denote an that a unit number identifies an -internal unit. (Fortran 2008 or later.) - -@item @code{NUMERIC_STORAGE_SIZE}: -The size in bits of the numeric storage unit. - -@item @code{LOGICAL_KINDS}: -Default-kind integer constant array of rank one containing the supported kind -parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) - -@item @code{OUTPUT_UNIT}: -Identifies the preconnected unit identified by the asterisk -(@code{*}) in @code{WRITE} statement. - -@item @code{REAL32}, @code{REAL64}, @code{REAL128}: -Kind type parameters to specify a REAL type with a storage -size of 32, 64, and 128 bits. It is negative if a target platform -does not support the particular kind. (Fortran 2008 or later.) - -@item @code{REAL_KINDS}: -Default-kind integer constant array of rank one containing the supported kind -parameters of the @code{REAL} type. (Fortran 2008 or later.) - -@item @code{STAT_LOCKED}: -Scalar default-integer constant used as STAT= return value by @code{LOCK} to -denote that the lock variable is locked by the executing image. (Fortran 2008 -or later.) - -@item @code{STAT_LOCKED_OTHER_IMAGE}: -Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to -denote that the lock variable is locked by another image. (Fortran 2008 or -later.) - -@item @code{STAT_STOPPED_IMAGE}: -Positive, scalar default-integer constant used as STAT= return value if the -argument in the statement requires synchronisation with an image, which has -initiated the termination of the execution. (Fortran 2008 or later.) - -@item @code{STAT_UNLOCKED}: -Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to -denote that the lock variable is unlocked. (Fortran 2008 or later.) -@end table - -The module provides the following derived type: - -@table @asis -@item @code{LOCK_TYPE}: -Derived type with private components to be use with the @code{LOCK} and -@code{UNLOCK} statement. A variable of its type has to be always declared -as coarray and may not appear in a variable-definition context. -(Fortran 2008 or later.) -@end table - -The module also provides the following intrinsic procedures: -@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. - - - -@node ISO_C_BINDING -@section @code{ISO_C_BINDING} -@table @asis -@item @emph{Standard}: -Fortran 2003 and later, GNU extensions -@end table - -The following intrinsic procedures are provided by the module; their -definition can be found in the section Intrinsic Procedures of this -manual. - -@table @asis -@item @code{C_ASSOCIATED} -@item @code{C_F_POINTER} -@item @code{C_F_PROCPOINTER} -@item @code{C_FUNLOC} -@item @code{C_LOC} -@item @code{C_SIZEOF} -@end table -@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, -@c don't really know why. - -The @code{ISO_C_BINDING} module provides the following named constants of -type default integer, which can be used as KIND type parameters. - -In addition to the integer named constants required by the Fortran 2003 -standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an -extension named constants for the 128-bit integer types supported by the -C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. -Furthermore, if @code{__float128} is supported in C, the named constants -@code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined. - -@multitable @columnfractions .15 .35 .35 .35 -@item Fortran Type @tab Named constant @tab C type @tab Extension -@item @code{INTEGER}@tab @code{C_INT} @tab @code{int} -@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} -@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} -@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} -@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} -@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} -@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} -@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} -@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} -@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} -@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. -@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} -@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} -@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} -@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} -@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. -@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} -@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} -@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} -@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} -@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. -@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} -@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} -@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113 -@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} -@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} -@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} -@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext. -@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} -@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} -@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} -@item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext. -@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} -@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} -@end multitable - -Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} -are defined. - -@multitable @columnfractions .20 .45 .15 -@item Name @tab C definition @tab Value -@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} -@item @code{C_ALERT} @tab alert @tab @code{'\a'} -@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} -@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} -@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} -@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} -@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} -@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} -@end multitable - -Moreover, the following two named constants are defined: - -@multitable @columnfractions .20 .80 -@item Name @tab Type -@item @code{C_NULL_PTR} @tab @code{C_PTR} -@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} -@end multitable - -Both are equivalent to the value @code{NULL} in C. - -@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS -@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} -@table @asis -@item @emph{Standard}: -OpenMP Application Program Interface v3.1 -@end table - - -The OpenMP Fortran runtime library routines are provided both in -a form of two Fortran 90 modules, named @code{OMP_LIB} and -@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named -@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found -in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual, -the named constants defined in the modules are listed -below. - -For details refer to the actual -@uref{http://www.openmp.org/mp-documents/spec31.pdf, -OpenMP Application Program Interface v3.1}. - -@code{OMP_LIB_KINDS} provides the following scalar default-integer -named constants: - -@table @asis -@item @code{omp_lock_kind} -@item @code{omp_nest_lock_kind} -@item @code{omp_sched_kind} -@end table - -@code{OMP_LIB} provides the scalar default-integer -named constant @code{openmp_version} with a value of the form -@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month -of the OpenMP version; for OpenMP v3.1 the value is @code{201107}. - -And the following scalar integer named constants of the -kind @code{omp_sched_kind}: - -@table @asis -@item @code{omp_sched_static} -@item @code{omp_sched_dynamic} -@item @code{omp_sched_guided} -@item @code{omp_sched_auto} -@end table |