| @ignore |
| Copyright (C) 2005-2022 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\acosd{\mathop{\rm acosd}\nolimits} |
| \gdef\asind{\mathop{\rm asind}\nolimits} |
| \gdef\atand{\mathop{\rm atand}\nolimits} |
| \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} |
| \gdef\cosd{\mathop{\rm cosd}\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{ACOSD}: ACOSD, Arccosine function, degrees |
| * @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{ASIND}: ASIND, Arcsine function, degrees |
| * @code{ASINH}: ASINH, Inverse hyperbolic sine function |
| * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair |
| * @code{ATAN}: ATAN, Arctangent function |
| * @code{ATAND}: ATAND, Arctangent function, degrees |
| * @code{ATAN2}: ATAN2, Arctangent function |
| * @code{ATAN2D}: ATAN2D, Arctangent function, degrees |
| * @code{ATANH}: ATANH, Inverse hyperbolic tangent function |
| * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation |
| * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation |
| * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap |
| * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically |
| * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch |
| * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch |
| * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch |
| * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch |
| * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation |
| * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically |
| * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation |
| * @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{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images |
| * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images |
| * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images |
| * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images |
| * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images |
| * @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{COSD}: COSD, Cosine function, degrees |
| * @code{COSH}: COSH, Hyperbolic cosine function |
| * @code{COTAN}: COTAN, Cotangent function |
| * @code{COTAND}: COTAND, Cotangent function, degrees |
| * @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{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred |
| * @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{FINDLOC}: FINDLOC, Search an array for a value |
| * @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_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous |
| * @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{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_INIT}: RANDOM_INIT, Initialize pseudo-random number generator |
| * @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{SIND}: SIND, Sine function, degrees |
| * @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{TAND}: TAND, Tangent function, degrees |
| * @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 procedures required |
| by the Fortran 95 and later supported standards, and a set of intrinsic |
| procedures for backwards compatibility with G77. Any conflict between |
| a description here and a description in the Fortran standards 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=} command-line option, |
| 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}, @gol |
| @ref{KILL}, @gol |
| @ref{BACKTRACE} |
| @end table |
| |
| |
| |
| @node ABS |
| @section @code{ABS} --- Absolute value |
| @fnindex ABS |
| @fnindex CABS |
| @fnindex DABS |
| @fnindex IABS |
| @fnindex ZABS |
| @fnindex CDABS |
| @fnindex BABS |
| @fnindex IIABS |
| @fnindex JIABS |
| @fnindex KIABS |
| @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 .23 .20 .33 |
| @headitem 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{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension |
| @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(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. Trailing 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 |
| @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}, @gol |
| @ref{IACHAR}, @gol |
| @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 .23 .20 .33 |
| @headitem 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: @gol |
| @ref{COS} @gol |
| Degrees function: @gol |
| @ref{ACOSD} |
| @end table |
| |
| |
| |
| @node ACOSD |
| @section @code{ACOSD} --- Arccosine function, degrees |
| @fnindex ACOSD |
| @fnindex DACOSD |
| @cindex trigonometric function, cosine, inverse, degrees |
| @cindex cosine, inverse, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of |
| @code{COSD(X)}). |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math} |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = ACOSD(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 degrees and lies in the range |
| @math{0 \leq \Re \acos(x) \leq 180}. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_acosd |
| real(8) :: x = 0.866_8 |
| x = acosd(x) |
| end program test_acosd |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{COSD} @gol |
| Radians function: @gol |
| @ref{ACOS} @gol |
| @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 .23 .20 .33 |
| @headitem 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: @gol |
| @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}, @gol |
| @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 90 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}, @gol |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later |
| @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 .23 .20 .33 |
| @headitem 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 90 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 90 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 or a boz-literal-constant. |
| @item @var{J} @tab The type shall be the same as the type of @var{I} or |
| a boz-literal-constant. @var{I} and @var{J} shall not both be |
| boz-literal-constants. If either @var{I} or @var{J} is a |
| boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. |
| @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. A boz-literal-constant is |
| converted to an @code{INTEGER} with the kind type parameter of |
| the other argument as-if a call to @ref{INT} occurred. |
| |
| @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: @gol |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ANINT(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 90 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 .23 .20 .33 |
| @headitem 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: @gol |
| @ref{SIN} @gol |
| Degrees function: @gol |
| @ref{ASIND} |
| @end table |
| |
| |
| |
| @node ASIND |
| @section @code{ASIND} --- Arcsine function, degrees |
| @fnindex ASIND |
| @fnindex DASIND |
| @cindex trigonometric function, sine, inverse, degrees |
| @cindex sine, inverse, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of |
| @code{SIND(X)}). |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = ASIND(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 degrees and lies in the range |
| @math{-90 \leq \Re \asin(x) \leq 90}. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_asind |
| real(8) :: x = 0.866_8 |
| x = asind(x) |
| end program test_asind |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{SIND} @gol |
| Radians function: @gol |
| @ref{ASIN} |
| @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 .23 .20 .33 |
| @headitem 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: @gol |
| @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 90 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} @tab The type and kind type parameter shall be the same 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 .23 .20 .33 |
| @headitem 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: @gol |
| @ref{TAN} @gol |
| Degrees function: @gol |
| @ref{ATAND} |
| @end table |
| |
| |
| |
| @node ATAND |
| @section @code{ATAND} --- Arctangent function, degrees |
| @fnindex ATAND |
| @fnindex DATAND |
| @cindex trigonometric function, tangent, inverse, degrees |
| @cindex tangent, inverse, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of |
| @ref{TAND}). |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @multitable @columnfractions .80 |
| @item @code{RESULT = ATAND(X)} |
| @item @code{RESULT = ATAND(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} @tab The type and kind type parameter shall be the same 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{ATAND2(Y,X)}. |
| Otherwise, it is the arcus tangent of @var{X}, where the real part of |
| the result is in degrees and lies in the range |
| @math{-90 \leq \Re \atand(x) \leq 90}. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_atand |
| real(8) :: x = 2.866_8 |
| x = atand(x) |
| end program test_atand |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .23 .23 .20 .30 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{TAND} @gol |
| Radians function: @gol |
| @ref{ATAN} |
| @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 .22 .22 .20 .32 |
| @headitem 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 |
| |
| @item @emph{See also}: |
| Alias: @gol |
| @ref{ATAN} @gol |
| Degrees function: @gol |
| @ref{ATAN2D} |
| @end table |
| |
| |
| |
| @node ATAN2D |
| @section @code{ATAN2D} --- Arctangent function, degrees |
| @fnindex ATAN2D |
| @fnindex DATAN2D |
| @cindex trigonometric function, tangent, inverse, degrees |
| @cindex tangent, inverse, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATAN2D(Y, X)} computes the principal value of the argument |
| function of the complex number @math{X + i Y} in degrees. This function can |
| be used to transform from Cartesian into polar coordinates and |
| allows to determine the angle in the correct quadrant. |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = ATAN2D(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{-180 \le \atan (x) \leq 180}. |
| 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{180} if |
| @var{X} is negative and @var{Y} is positive zero (or the processor does |
| not handle signed zeros), and @math{-180} 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{90}. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_atan2d |
| real(4) :: x = 1.e0_4, y = 0.5e0_4 |
| x = atan2d(y,x) |
| end program test_atan2d |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .23 .23 .20 .30 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Alias: @gol |
| @ref{ATAND} @gol |
| Radians function: @gol |
| @ref{ATAN2} |
| @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 .23 .20 .33 |
| @headitem 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: @gol |
| @ref{TANH} |
| @end table |
| |
| |
| |
| @node ATOMIC_ADD |
| @section @code{ATOMIC_ADD} --- Atomic ADD operation |
| @fnindex ATOMIC_ADD |
| @cindex Atomic subroutine, add |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VALUE} to the |
| variable @var{ATOM}. When @var{STAT} is present and the invocation was |
| successful, it is assigned the value 0. If it is present and the invocation |
| has failed, it is assigned a positive value; in particular, for a coindexed |
| @var{ATOM}, if the remote image has stopped, it is assigned the value of |
| @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has |
| failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*] |
| call atomic_add (atom[1], this_image()) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_FETCH_ADD}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_AND}, @gol |
| @ref{ATOMIC_OR}, @gol |
| @ref{ATOMIC_XOR} |
| @end table |
| |
| |
| |
| |
| @node ATOMIC_AND |
| @section @code{ATOMIC_AND} --- Atomic bitwise AND operation |
| @fnindex ATOMIC_AND |
| @cindex Atomic subroutine, AND |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise |
| AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present |
| and the invocation was successful, it is assigned the value 0. If it is present |
| and the invocation has failed, it is assigned a positive value; in particular, |
| for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the |
| value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote |
| image has failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*] |
| call atomic_and (atom[1], int(b'10100011101')) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_FETCH_AND}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_ADD}, @gol |
| @ref{ATOMIC_OR}, @gol |
| @ref{ATOMIC_XOR} |
| @end table |
| |
| |
| |
| @node ATOMIC_CAS |
| @section @code{ATOMIC_CAS} --- Atomic compare and swap |
| @fnindex ATOMIC_DEFINE |
| @cindex Atomic subroutine, compare and swap |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of |
| @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value |
| of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} |
| that was used for the comparison. When @var{STAT} is present and the invocation |
| was successful, it is assigned the value 0. If it is present and the invocation |
| has failed, it is assigned a positive value; in particular, for a coindexed |
| @var{ATOM}, if the remote image has stopped, it is assigned the value of |
| @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has |
| failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} |
| |
| @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{OLD} @tab Scalar of the same type and kind as @var{ATOM}. |
| @item @var{COMPARE} @tab Scalar variable of the same type and kind as |
| @var{ATOM}. |
| @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| logical(atomic_logical_kind) :: atom[*], prev |
| call atomic_cas (atom[1], prev, .false., .true.)) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_REF}, @gol |
| @ref{ISO_FORTRAN_ENV} |
| @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. When @var{STAT} is present and the invocation was |
| successful, it is assigned the value 0. If it is present and the invocation |
| has failed, it is assigned a positive value; in particular, for a coindexed |
| @var{ATOM}, if the remote image has stopped, it is assigned the value of |
| @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has |
| failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| Fortran 2008 and later; with @var{STAT}, TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} |
| |
| @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{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @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}, @gol |
| @ref{ATOMIC_CAS}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_ADD}, @gol |
| @ref{ATOMIC_AND}, @gol |
| @ref{ATOMIC_OR}, @gol |
| @ref{ATOMIC_XOR} |
| @end table |
| |
| |
| |
| @node ATOMIC_FETCH_ADD |
| @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch |
| @fnindex ATOMIC_FETCH_ADD |
| @cindex Atomic subroutine, ADD with fetch |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of |
| @var{ATOM} in @var{OLD} and adds the value of @var{VALUE} to the |
| variable @var{ATOM}. When @var{STAT} is present and the invocation was |
| successful, it is assigned the value 0. If it is present and the invocation |
| has failed, it is assigned a positive value; in particular, for a coindexed |
| @var{ATOM}, if the remote image has stopped, it is assigned the value of |
| @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has |
| failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @code{ATOMIC_LOGICAL_KIND} kind. |
| |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*], old |
| call atomic_add (atom[1], this_image(), old) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_ADD}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_FETCH_AND}, @gol |
| @ref{ATOMIC_FETCH_OR}, @gol |
| @ref{ATOMIC_FETCH_XOR} |
| @end table |
| |
| |
| |
| @node ATOMIC_FETCH_AND |
| @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch |
| @fnindex ATOMIC_FETCH_AND |
| @cindex Atomic subroutine, AND with fetch |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in |
| @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of |
| @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was |
| successful, it is assigned the value 0. If it is present and the invocation has |
| failed, it is assigned a positive value; in particular, for a coindexed |
| @var{ATOM}, if the remote image has stopped, it is assigned the value of |
| @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has |
| failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*], old |
| call atomic_fetch_and (atom[1], int(b'10100011101'), old) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_AND}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_FETCH_ADD}, @gol |
| @ref{ATOMIC_FETCH_OR}, @gol |
| @ref{ATOMIC_FETCH_XOR} |
| @end table |
| |
| |
| |
| @node ATOMIC_FETCH_OR |
| @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch |
| @fnindex ATOMIC_FETCH_OR |
| @cindex Atomic subroutine, OR with fetch |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in |
| @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of |
| @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was |
| successful, it is assigned the value 0. If it is present and the invocation has |
| failed, it is assigned a positive value; in particular, for a coindexed |
| @var{ATOM}, if the remote image has stopped, it is assigned the value of |
| @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has |
| failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*], old |
| call atomic_fetch_or (atom[1], int(b'10100011101'), old) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_OR}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_FETCH_ADD}, @gol |
| @ref{ATOMIC_FETCH_AND}, @gol |
| @ref{ATOMIC_FETCH_XOR} |
| @end table |
| |
| |
| |
| @node ATOMIC_FETCH_XOR |
| @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch |
| @fnindex ATOMIC_FETCH_XOR |
| @cindex Atomic subroutine, XOR with fetch |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in |
| @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of |
| @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was |
| successful, it is assigned the value 0. If it is present and the invocation has |
| failed, it is assigned a positive value; in particular, for a coindexed |
| @var{ATOM}, if the remote image has stopped, it is assigned the value of |
| @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has |
| failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*], old |
| call atomic_fetch_xor (atom[1], int(b'10100011101'), old) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_XOR}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_FETCH_ADD}, @gol |
| @ref{ATOMIC_FETCH_AND}, @gol |
| @ref{ATOMIC_FETCH_OR} |
| @end table |
| |
| |
| |
| @node ATOMIC_OR |
| @section @code{ATOMIC_OR} --- Atomic bitwise OR operation |
| @fnindex ATOMIC_OR |
| @cindex Atomic subroutine, OR |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise |
| AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present |
| and the invocation was successful, it is assigned the value 0. If it is present |
| and the invocation has failed, it is assigned a positive value; in particular, |
| for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the |
| value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote |
| image has failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*] |
| call atomic_or (atom[1], int(b'10100011101')) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_FETCH_OR}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_ADD}, @gol |
| @ref{ATOMIC_OR}, @gol |
| @ref{ATOMIC_XOR} |
| @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}. When @var{STAT} is present and the |
| invocation was successful, it is assigned the value 0. If it is present and the |
| invocation has failed, it is assigned a positive value; in particular, for a |
| coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value |
| of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image |
| has failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| |
| @item @emph{Standard}: |
| Fortran 2008 and later; with @var{STAT}, TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{VALUE} @tab Scalar 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. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @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}, @gol |
| @ref{ATOMIC_CAS}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_FETCH_ADD}, @gol |
| @ref{ATOMIC_FETCH_AND}, @gol |
| @ref{ATOMIC_FETCH_OR}, @gol |
| @ref{ATOMIC_FETCH_XOR} |
| @end table |
| |
| |
| @node ATOMIC_XOR |
| @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation |
| @fnindex ATOMIC_XOR |
| @cindex Atomic subroutine, XOR |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise |
| XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present |
| and the invocation was successful, it is assigned the value 0. If it is present |
| and the invocation has failed, it is assigned a positive value; in particular, |
| for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the |
| value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote |
| image has failed, the value @code{STAT_FAILED_IMAGE}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| Atomic subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer |
| type with @code{ATOMIC_INT_KIND} kind. |
| @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind |
| is different, the value is converted to the kind of @var{ATOM}. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| integer(atomic_int_kind) :: atom[*] |
| call atomic_xor (atom[1], int(b'10100011101')) |
| end program atomic |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{ATOMIC_DEFINE}, @gol |
| @ref{ATOMIC_FETCH_XOR}, @gol |
| @ref{ISO_FORTRAN_ENV}, @gol |
| @ref{ATOMIC_ADD}, @gol |
| @ref{ATOMIC_OR}, @gol |
| @ref{ATOMIC_XOR} |
| @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}. |
| @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 .21 .22 .20 .33 |
| @headitem 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}. |
| @end multitable |
| |
| @item @emph{Return value}: |
| The return value is of type @code{REAL} and 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 .23 .20 .33 |
| @headitem 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 .22 .22 .20 .32 |
| @headitem 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}. |
| @end multitable |
| |
| @item @emph{Return value}: |
| The return value is 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 .23 .20 .33 |
| @headitem 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}. |
| @end multitable |
| |
| @item @emph{Return value}: |
| The return value is 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 .23 .20 .33 |
| @headitem 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 .23 .20 .33 |
| @headitem 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}, @gol |
| @ref{BLE}, @gol |
| @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}, @gol |
| @ref{BLE}, @gol |
| @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 90 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}, @gol |
| @ref{BGE}, @gol |
| @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}, @gol |
| @ref{BGT}, @gol |
| @ref{BLE} |
| @end table |
| |
| |
| |
| @node BTEST |
| @section @code{BTEST} --- Bit test function |
| @fnindex BTEST |
| @fnindex BBTEST |
| @fnindex BITEST |
| @fnindex BJTEST |
| @fnindex BKTEST |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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 |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .21 .28 .18 .30 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later |
| @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension |
| @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension |
| @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension |
| @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension |
| @end multitable |
| @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_ptr_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_ptr_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}, @gol |
| @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}, @gol |
| @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}, @gol |
| @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}, @gol |
| @ref{C_LOC}, @gol |
| @ref{C_F_POINTER}, @gol |
| @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}, @gol |
| @ref{C_FUNLOC}, @gol |
| @ref{C_F_POINTER}, @gol |
| @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{T} unless you are using a platform |
| where default @code{REAL} variables are unusually padded. |
| |
| @item @emph{See also}: |
| @ref{SIZEOF}, @gol |
| @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}, @gol |
| @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 .19 .19 .25 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 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}, @gol |
| @ref{IACHAR}, @gol |
| @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 CO_BROADCAST |
| @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images |
| @fnindex CO_BROADCAST |
| @cindex Collectives, value broadcasting |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{CO_BROADCAST} copies the value of argument @var{A} on the image with |
| image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} |
| becomes defined as if by intrinsic assignment. If the execution was |
| successful and @var{STAT} is present, it is assigned the value zero. If the |
| execution failed, @var{STAT} gets assigned a nonzero value and, if present, |
| @var{ERRMSG} gets assigned a value describing the occurred error. |
| |
| @item @emph{Standard}: |
| Technical Specification (TS) 18508 or later |
| |
| @item @emph{Class}: |
| Collective subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .20 .65 |
| @item @var{A} @tab INTENT(INOUT) argument; shall have the same |
| dynamic type and type parameters on all images of the current team. If it |
| is an array, it shall have the same shape on all images. |
| @item @var{SOURCE_IMAGE} @tab a scalar integer expression. |
| It shall have the same value on all images and refer to an |
| image of the current team. |
| @item @var{STAT} @tab (optional) a scalar integer variable |
| @item @var{ERRMSG} @tab (optional) a scalar character variable |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program test |
| integer :: val(3) |
| if (this_image() == 1) then |
| val = [1, 5, 3] |
| end if |
| call co_broadcast (val, source_image=1) |
| print *, this_image, ":", val |
| end program test |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{CO_MAX}, @gol |
| @ref{CO_MIN}, @gol |
| @ref{CO_SUM}, @gol |
| @ref{CO_REDUCE} |
| @end table |
| |
| |
| |
| @node CO_MAX |
| @section @code{CO_MAX} --- Maximal value on the current set of images |
| @fnindex CO_MAX |
| @cindex Collectives, maximal value |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{CO_MAX} determines element-wise the maximal value of @var{A} on all |
| images of the current team. If @var{RESULT_IMAGE} is present, the maximum |
| values are returned in @var{A} on the specified image only and the value |
| of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is |
| not present, the value is returned on all images. If the execution was |
| successful and @var{STAT} is present, it is assigned the value zero. If the |
| execution failed, @var{STAT} gets assigned a nonzero value and, if present, |
| @var{ERRMSG} gets assigned a value describing the occurred error. |
| |
| @item @emph{Standard}: |
| Technical Specification (TS) 18508 or later |
| |
| @item @emph{Class}: |
| Collective subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .20 .65 |
| @item @var{A} @tab shall be an integer, real or character variable, |
| which has the same type and type parameters on all images of the team. |
| @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if |
| present, it shall have the same value on all images and refer to an |
| image of the current team. |
| @item @var{STAT} @tab (optional) a scalar integer variable |
| @item @var{ERRMSG} @tab (optional) a scalar character variable |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program test |
| integer :: val |
| val = this_image () |
| call co_max (val, result_image=1) |
| if (this_image() == 1) then |
| write(*,*) "Maximal value", val ! prints num_images() |
| end if |
| end program test |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{CO_MIN}, @gol |
| @ref{CO_SUM}, @gol |
| @ref{CO_REDUCE}, @gol |
| @ref{CO_BROADCAST} |
| @end table |
| |
| |
| |
| @node CO_MIN |
| @section @code{CO_MIN} --- Minimal value on the current set of images |
| @fnindex CO_MIN |
| @cindex Collectives, minimal value |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{CO_MIN} determines element-wise the minimal value of @var{A} on all |
| images of the current team. If @var{RESULT_IMAGE} is present, the minimal |
| values are returned in @var{A} on the specified image only and the value |
| of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is |
| not present, the value is returned on all images. If the execution was |
| successful and @var{STAT} is present, it is assigned the value zero. If the |
| execution failed, @var{STAT} gets assigned a nonzero value and, if present, |
| @var{ERRMSG} gets assigned a value describing the occurred error. |
| |
| @item @emph{Standard}: |
| Technical Specification (TS) 18508 or later |
| |
| @item @emph{Class}: |
| Collective subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .20 .65 |
| @item @var{A} @tab shall be an integer, real or character variable, |
| which has the same type and type parameters on all images of the team. |
| @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if |
| present, it shall have the same value on all images and refer to an |
| image of the current team. |
| @item @var{STAT} @tab (optional) a scalar integer variable |
| @item @var{ERRMSG} @tab (optional) a scalar character variable |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program test |
| integer :: val |
| val = this_image () |
| call co_min (val, result_image=1) |
| if (this_image() == 1) then |
| write(*,*) "Minimal value", val ! prints 1 |
| end if |
| end program test |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{CO_MAX}, @gol |
| @ref{CO_SUM}, @gol |
| @ref{CO_REDUCE}, @gol |
| @ref{CO_BROADCAST} |
| @end table |
| |
| |
| |
| @node CO_REDUCE |
| @section @code{CO_REDUCE} --- Reduction of values on the current set of images |
| @fnindex CO_REDUCE |
| @cindex Collectives, generic reduction |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} |
| on all images of the current team. The pure function passed as @var{OPERATION} |
| is used to pairwise reduce the values of @var{A} by passing either the value |
| of @var{A} of different images or the result values of such a reduction as |
| argument. If @var{A} is an array, the deduction is done element wise. If |
| @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on |
| the specified image only and the value of @var{A} on the other images become |
| undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all |
| images. If the execution was successful and @var{STAT} is present, it is |
| assigned the value zero. If the execution failed, @var{STAT} gets assigned |
| a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing |
| the occurred error. |
| |
| @item @emph{Standard}: |
| Technical Specification (TS) 18508 or later |
| |
| @item @emph{Class}: |
| Collective subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL CO_REDUCE(A, OPERATION, [, RESULT_IMAGE, STAT, ERRMSG])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .20 .65 |
| @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be |
| nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, |
| it shall be associated. @var{A} shall have the same type and type parameters on |
| all images of the team; if it is an array, it shall have the same shape on all |
| images. |
| @item @var{OPERATION} @tab pure function with two scalar nonallocatable |
| arguments, which shall be nonpolymorphic and have the same type and type |
| parameters as @var{A}. The function shall return a nonallocatable scalar of |
| the same type and type parameters as @var{A}. The function shall be the same on |
| all images and with regards to the arguments mathematically commutative and |
| associative. Note that @var{OPERATION} may not be an elemental function, unless |
| it is an intrisic function. |
| @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if |
| present, it shall have the same value on all images and refer to an |
| image of the current team. |
| @item @var{STAT} @tab (optional) a scalar integer variable |
| @item @var{ERRMSG} @tab (optional) a scalar character variable |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program test |
| integer :: val |
| val = this_image () |
| call co_reduce (val, result_image=1, operation=myprod) |
| if (this_image() == 1) then |
| write(*,*) "Product value", val ! prints num_images() factorial |
| end if |
| contains |
| pure function myprod(a, b) |
| integer, value :: a, b |
| integer :: myprod |
| myprod = a * b |
| end function myprod |
| end program test |
| @end smallexample |
| |
| @item @emph{Note}: |
| While the rules permit in principle an intrinsic function, none of the |
| intrinsics in the standard fulfill the criteria of having a specific |
| function, which takes two arguments of the same type and returning that |
| type as result. |
| |
| @item @emph{See also}: |
| @ref{CO_MIN}, @gol |
| @ref{CO_MAX}, @gol |
| @ref{CO_SUM}, @gol |
| @ref{CO_BROADCAST} |
| @end table |
| |
| |
| |
| @node CO_SUM |
| @section @code{CO_SUM} --- Sum of values on the current set of images |
| @fnindex CO_SUM |
| @cindex Collectives, sum of values |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{CO_SUM} sums up the values of each element of @var{A} on all |
| images of the current team. If @var{RESULT_IMAGE} is present, the summed-up |
| values are returned in @var{A} on the specified image only and the value |
| of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is |
| not present, the value is returned on all images. If the execution was |
| successful and @var{STAT} is present, it is assigned the value zero. If the |
| execution failed, @var{STAT} gets assigned a nonzero value and, if present, |
| @var{ERRMSG} gets assigned a value describing the occurred error. |
| |
| @item @emph{Standard}: |
| Technical Specification (TS) 18508 or later |
| |
| @item @emph{Class}: |
| Collective subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .20 .65 |
| @item @var{A} @tab shall be an integer, real or complex variable, |
| which has the same type and type parameters on all images of the team. |
| @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if |
| present, it shall have the same value on all images and refer to an |
| image of the current team. |
| @item @var{STAT} @tab (optional) a scalar integer variable |
| @item @var{ERRMSG} @tab (optional) a scalar character variable |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program test |
| integer :: val |
| val = this_image () |
| call co_sum (val, result_image=1) |
| if (this_image() == 1) then |
| write(*,*) "The sum is ", val ! prints (n**2 + n)/2, |
| ! with n = num_images() |
| end if |
| end program test |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{CO_MAX}, @gol |
| @ref{CO_MIN}, @gol |
| @ref{CO_REDUCE}, @gol |
| @ref{CO_BROADCAST} |
| @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}, @gol |
| @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}, @gol |
| @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}, @gol |
| @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 an overload that is a GNU extension |
| |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @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 .23 .20 .33 |
| @headitem 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: @gol |
| @ref{ACOS} @gol |
| Degrees function: @gol |
| @ref{COSD} |
| @end table |
| |
| |
| |
| @node COSD |
| @section @code{COSD} --- Cosine function, degrees |
| @fnindex COSD |
| @fnindex DCOSD |
| @fnindex CCOSD |
| @fnindex ZCOSD |
| @fnindex CDCOSD |
| @cindex trigonometric function, cosine, degrees |
| @cindex cosine, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{COSD(X)} computes the cosine of @var{X} in degrees. |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = COSD(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 degrees. If @var{X} is of the type @code{REAL}, |
| the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_cosd |
| real :: x = 0.0 |
| x = cosd(x) |
| end program test_cosd |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension |
| @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{ACOSD} @gol |
| Radians function: @gol |
| @ref{COS} |
| @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 .23 .20 .33 |
| @headitem 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: @gol |
| @ref{ACOSH} |
| @end table |
| |
| |
| |
| @node COTAN |
| @section @code{COTAN} --- Cotangent function |
| @fnindex COTAN |
| @fnindex DCOTAN |
| @cindex trigonometric function, cotangent |
| @cindex cotangent |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)} |
| divided by @code{SIN(x)}, or @code{1 / TAN(x)}. |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = COTAN(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}, and its value is in radians. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_cotan |
| real(8) :: x = 0.165_8 |
| x = cotan(x) |
| end program test_cotan |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Converse function: @gol |
| @ref{TAN} @gol |
| Degrees function: @gol |
| @ref{COTAND} |
| @end table |
| |
| |
| |
| @node COTAND |
| @section @code{COTAND} --- Cotangent function, degrees |
| @fnindex COTAND |
| @fnindex DCOTAND |
| @cindex trigonometric function, cotangent, degrees |
| @cindex cotangent, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to |
| @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = COTAND(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}, and its value is in degrees. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_cotand |
| real(8) :: x = 0.165_8 |
| x = cotand(x) |
| end program test_cotand |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Converse function: @gol |
| @ref{TAND} @gol |
| Radians function: @gol |
| @ref{COTAN} |
| @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 90 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}, @gol |
| @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 90 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 |
| @ref{TIME8}, to a string. The output will be of the form @samp{Sat |
| Aug 19 18:13:14 1995}. |
| |
| 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}, @gol |
| @ref{GMTIME}, @gol |
| @ref{LTIME}, @gol |
| @ref{TIME}, @gol |
| @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 .70 |
| @item @code{VALUE(1)}: @tab The year |
| @item @code{VALUE(2)}: @tab The month |
| @item @code{VALUE(3)}: @tab The day of the month |
| @item @code{VALUE(4)}: @tab Time difference with UTC in minutes |
| @item @code{VALUE(5)}: @tab The hour of the day |
| @item @code{VALUE(6)}: @tab The minutes of the hour |
| @item @code{VALUE(7)}: @tab The seconds of the minute |
| @item @code{VALUE(8)}: @tab The milliseconds of the second |
| @end multitable |
| |
| @item @emph{Standard}: |
| Fortran 90 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}, @gol |
| @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 90 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}. (As |
| a GNU extension, arguments of different kinds are permitted.) |
| @end multitable |
| |
| @item @emph{Return value}: |
| The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU |
| extension, kind is the largest kind of the actual arguments.) |
| |
| @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 .26 .20 .30 |
| @headitem 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 90 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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @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 .70 |
| @item @code{VALUES(1)}: @tab User time in seconds. |
| @item @code{VALUES(2)}: @tab System time in seconds. |
| @item @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 90 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 90 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 .23 .20 .33 |
| @headitem 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 .23 .20 .33 |
| @headitem 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 .70 |
| @item @code{VALUES(1)}: @tab User time in seconds. |
| @item @code{VALUES(2)}: @tab System time in seconds. |
| @item @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 EVENT_QUERY |
| @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred |
| @fnindex EVENT_QUERY |
| @cindex Events, EVENT_QUERY |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been |
| posted to the @var{EVENT} variable and not yet been removed by calling |
| @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful, |
| it is assigned the value 0. If it is present and the invocation has failed, |
| it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}. |
| |
| @item @emph{Standard}: |
| TS 18508 or later |
| |
| @item @emph{Class}: |
| subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE}, |
| defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed. |
| @item @var{COUNT} @tab (intent(out))Scalar integer with at least the |
| precision of default integer. |
| @item @var{STAT} @tab (optional) Scalar default-kind integer variable. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program atomic |
| use iso_fortran_env |
| implicit none |
| type(event_type) :: event_value_has_been_set[*] |
| integer :: cnt |
| if (this_image() == 1) then |
| call event_query (event_value_has_been_set, cnt) |
| if (cnt > 0) write(*,*) "Value has been set" |
| elseif (this_image() == 2) then |
| event post (event_value_has_been_set[1]) |
| end if |
| end program atomic |
| @end smallexample |
| |
| @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 (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 using the C library's @code{system} |
| call. |
| |
| 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. |
| |
| For asynchronous execution on supported targets, the POSIX |
| @code{posix_spawn} or @code{fork} functions are used. Also, a signal |
| handler for the @code{SIGCHLD} signal is installed. |
| |
| @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}, @gol |
| @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 .23 .20 .33 |
| @headitem 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 90 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 |
| @ref{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}, @gol |
| @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}, @gol |
| @ref{FPUT}, @gol |
| @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}, @gol |
| @ref{FPUT}, @gol |
| @ref{FPUTC} |
| @end table |
| |
| @node FINDLOC |
| @section @code{FINDLOC} --- Search an array for a value |
| @fnindex FINDLOC |
| @cindex findloc |
| |
| @table @asis |
| @item @emph{Description}: |
| Determines the location of the element in the array with the value |
| given in the @var{VALUE} argument, or, if the @var{DIM} argument is |
| supplied, determines the locations of the elements equal to the |
| @var{VALUE} argument 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 value |
| @var{VALUE}, the location returned is that of the first such element |
| in array element order if the @var{BACK} is not present or if it is |
| @code{.FALSE.}. If @var{BACK} is true, the location returned is that |
| of the last such element. 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 2008 and later. |
| |
| @item @emph{Class}: |
| Transformational function |
| |
| @item @emph{Syntax}: |
| @multitable @columnfractions .80 |
| @item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])} |
| @item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])} |
| @end multitable |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ARRAY} @tab Shall be an array of intrinsic type. |
| @item @var{VALUE} @tab A scalar of intrinsic type which is in type |
| conformance with @var{ARRAY}. |
| @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 (Optional) Shall be of type @code{LOGICAL}, |
| and conformable with @var{ARRAY}. |
| @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization |
| expression indicating the kind parameter of the result. |
| @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. |
| @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. If the optional argument @var{KIND} |
| is present, the result is an integer of kind @var{KIND}, otherwise it |
| is of default kind. |
| |
| @item @emph{See also}: |
| @ref{MAXLOC}, @gol |
| @ref{MINLOC} |
| |
| @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}, @gol |
| @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}, @gol |
| @ref{FGET}, @gol |
| @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}, @gol |
| @ref{FGET}, @gol |
| @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 90 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: @gol |
| @ref{LSTAT} @gol |
| To stat a file: @gol |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @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: @gol |
| @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 be of type @code{CHARACTER} and of default kind. |
| @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}, @gol |
| @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. |
| @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} cannot 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: @gol |
| @ref{IARGC} @gol |
| Fortran 2003 functions and subroutines: @gol |
| @ref{GET_COMMAND}, @gol |
| @ref{GET_COMMAND_ARGUMENT}, @gol |
| @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}, @gol |
| @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} cannot 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}, @gol |
| @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}, @gol |
| @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{C}. (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}, @gol |
| @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}, @gol |
| @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 @ref{TIME} |
| 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)}. |
| |
| This intrinsic routine is provided for backwards compatibility with |
| GNU Fortran 77. In new code, programmers should consider the use of |
| the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 |
| standard. |
| |
| @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 1--31 |
| @item Number of months since January, range 0--11 |
| @item Years since 1900 |
| @item Number of days since Sunday, range 0--6 |
| @item Days since January 1, range 0--365 |
| @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{DATE_AND_TIME}, @gol |
| @ref{CTIME}, @gol |
| @ref{LTIME}, @gol |
| @ref{TIME}, @gol |
| @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 90 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}, @gol |
| @ref{CHAR}, @gol |
| @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}, @gol |
| @ref{IPARITY}, @gol |
| @ref{IAND} |
| @end table |
| |
| |
| |
| @node IAND |
| @section @code{IAND} --- Bitwise logical and |
| @fnindex IAND |
| @fnindex BIAND |
| @fnindex IIAND |
| @fnindex JIAND |
| @fnindex KIAND |
| @cindex bitwise logical and |
| @cindex logical and, bitwise |
| |
| @table @asis |
| @item @emph{Description}: |
| Bitwise logical @code{AND}. |
| |
| @item @emph{Standard}: |
| Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions |
| |
| @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} or a boz-literal-constant. |
| @item @var{J} @tab The type shall be @code{INTEGER} with the same |
| kind type parameter as @var{I} or a boz-literal-constant. |
| @var{I} and @var{J} shall not both be boz-literal-constants. |
| @end multitable |
| |
| @item @emph{Return value}: |
| The return type is @code{INTEGER} with the kind type parameter of the |
| arguments. |
| A boz-literal-constant is converted to an @code{INTEGER} with the kind |
| type parameter of the other argument as-if a call to @ref{INT} occurred. |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{IOR}, @gol |
| @ref{IEOR}, @gol |
| @ref{IBITS}, @gol |
| @ref{IBSET}, @gol |
| @ref{IBCLR}, @gol |
| @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}, @gol |
| @ref{IALL}, @gol |
| @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: @gol |
| @ref{GETARG} @gol |
| Fortran 2003 functions and subroutines: @gol |
| @ref{GET_COMMAND}, @gol |
| @ref{GET_COMMAND_ARGUMENT}, @gol |
| @ref{COMMAND_ARGUMENT_COUNT} |
| @end table |
| |
| |
| |
| @node IBCLR |
| @section @code{IBCLR} --- Clear bit |
| @fnindex IBCLR |
| @fnindex BBCLR |
| @fnindex IIBCLR |
| @fnindex JIBCLR |
| @fnindex KIBCLR |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{IBITS}, @gol |
| @ref{IBSET}, @gol |
| @ref{IAND}, @gol |
| @ref{IOR}, @gol |
| @ref{IEOR}, @gol |
| @ref{MVBITS} |
| @end table |
| |
| |
| |
| @node IBITS |
| @section @code{IBITS} --- Bit extraction |
| @fnindex IBITS |
| @fnindex BBITS |
| @fnindex IIBITS |
| @fnindex JIBITS |
| @fnindex KIBITS |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{BIT_SIZE}, @gol |
| @ref{IBCLR}, @gol |
| @ref{IBSET}, @gol |
| @ref{IAND}, @gol |
| @ref{IOR}, @gol |
| @ref{IEOR} |
| @end table |
| |
| |
| |
| @node IBSET |
| @section @code{IBSET} --- Set bit |
| @fnindex IBSET |
| @fnindex BBSET |
| @fnindex IIBSET |
| @fnindex JIBSET |
| @fnindex KIBSET |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{IBCLR}, @gol |
| @ref{IBITS}, @gol |
| @ref{IAND}, @gol |
| @ref{IOR}, @gol |
| @ref{IEOR}, @gol |
| @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 77 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 .23 .20 .33 |
| @headitem 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}, @gol |
| @ref{CHAR}, @gol |
| @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. |
| |
| This intrinsic routine is provided for backwards compatibility with |
| GNU Fortran 77. In new code, programmers should consider the use of |
| the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 |
| standard. |
| |
| @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 |
| |
| @item @emph{See also}: |
| @ref{DATE_AND_TIME} |
| @end table |
| |
| |
| @node IEOR |
| @section @code{IEOR} --- Bitwise logical exclusive or |
| @fnindex IEOR |
| @fnindex BIEOR |
| @fnindex IIEOR |
| @fnindex JIEOR |
| @fnindex KIEOR |
| @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 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions |
| |
| @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} or a boz-literal-constant. |
| @item @var{J} @tab The type shall be @code{INTEGER} with the same |
| kind type parameter as @var{I} or a boz-literal-constant. |
| @var{I} and @var{J} shall not both be boz-literal-constants. |
| @end multitable |
| |
| @item @emph{Return value}: |
| The return type is @code{INTEGER} with the kind type parameter of the |
| arguments. |
| A boz-literal-constant is converted to an @code{INTEGER} with the kind |
| type parameter of the other argument as-if a call to @ref{INT} occurred. |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{IOR}, @gol |
| @ref{IAND}, @gol |
| @ref{IBITS}, @gol |
| @ref{IBSET}, @gol |
| @ref{IBCLR}, @gol |
| @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}: |
| @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}, @gol |
| @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 .35 .15 .17 .30 |
| @headitem 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}, @gol |
| @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, with boz-literal-constant Fortran 2008 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} or a boz-literal-constant. |
| @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)} is the integer |
| whose magnitude is the largest integer that does not exceed the magnitude |
| 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 .23 .20 .33 |
| @headitem 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 |
| @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. |
| |
| @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}, @gol |
| @ref{INT8} |
| @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}, @gol |
| @ref{INT2} |
| @end table |
| |
| |
| |
| @node IOR |
| @section @code{IOR} --- Bitwise logical or |
| @fnindex IOR |
| @fnindex BIOR |
| @fnindex IIOR |
| @fnindex JIOR |
| @fnindex KIOR |
| @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 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions |
| |
| @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} or a boz-literal-constant. |
| @item @var{J} @tab The type shall be @code{INTEGER} with the same |
| kind type parameter as @var{I} or a boz-literal-constant. |
| @var{I} and @var{J} shall not both be boz-literal-constants. |
| @end multitable |
| |
| @item @emph{Return value}: |
| The return type is @code{INTEGER} with the kind type parameter of the |
| arguments. |
| A boz-literal-constant is converted to an @code{INTEGER} with the kind |
| type parameter of the other argument as-if a call to @ref{INT} occurred. |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{IEOR}, @gol |
| @ref{IAND}, @gol |
| @ref{IBITS}, @gol |
| @ref{IBSET}, @gol |
| @ref{IBCLR}, @gol |
| @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) = int(b'00100100', 1) |
| a(2) = int(b'01101010', 1) |
| |
| ! prints 01001110 |
| PRINT '(b8.8)', IPARITY(a) |
| END PROGRAM |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{IANY}, @gol |
| @ref{IALL}, @gol |
| @ref{IEOR}, @gol |
| @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_CONTIGUOUS |
| @section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous |
| @fnindex IS_IOSTAT_EOR |
| @cindex array, contiguity |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{IS_CONTIGUOUS} tests whether an array is contiguous. |
| |
| @item @emph{Standard}: |
| Fortran 2008 and later |
| |
| @item @emph{Class}: |
| Inquiry function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = IS_CONTIGUOUS(ARRAY)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{ARRAY} @tab Shall be an array of any type. |
| @end multitable |
| |
| @item @emph{Return value}: |
| Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if |
| @var{ARRAY} is contiguous and false otherwise. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test |
| integer :: a(10) |
| a = [1,2,3,4,5,6,7,8,9,10] |
| call sub (a) ! every element, is contiguous |
| call sub (a(::2)) ! every other element, is noncontiguous |
| contains |
| subroutine sub (x) |
| integer :: x(:) |
| if (is_contiguous (x)) then |
| write (*,*) 'X is contiguous' |
| else |
| write (*,*) 'X is not contiguous' |
| end if |
| end subroutine sub |
| end program test |
| @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 |
| @fnindex BSHFT |
| @fnindex IISHFT |
| @fnindex JISHFT |
| @fnindex KISHFT |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{ISHFTC} |
| @end table |
| |
| |
| |
| @node ISHFTC |
| @section @code{ISHFTC} --- Shift bits circularly |
| @fnindex ISHFTC |
| @fnindex BSHFTC |
| @fnindex IISHFTC |
| @fnindex JISHFTC |
| @fnindex KISHFTC |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @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{ITIME(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. |
| |
| This intrinsic routine is provided for backwards compatibility with |
| GNU Fortran 77. In new code, programmers should consider the use of |
| the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 |
| standard. |
| |
| @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 |
| |
| @item @emph{See also}: |
| @ref{DATE_AND_TIME} |
| @end table |
| |
| |
| |
| @node KILL |
| @section @code{KILL} --- Send a signal to a process |
| @fnindex KILL |
| |
| @table @asis |
| @item @emph{Description}: |
| Sends the signal specified by @var{SIG} 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{Standard}: |
| GNU extension |
| |
| @item @emph{Standard}: |
| GNU extension |
| |
| @item @emph{Class}: |
| Subroutine, function |
| |
| @item @emph{Syntax}: |
| @multitable @columnfractions .80 |
| @item @code{CALL KILL(PID, SIG [, STATUS])} |
| @item @code{STATUS = KILL(PID, SIG)} |
| @end multitable |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. |
| @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. |
| @item @var{STATUS} @tab [Subroutine](Optional) |
| Shall be a scalar @code{INTEGER}. |
| Returns 0 on success; otherwise a system-specific error code is returned. |
| @item @var{STATUS} @tab [Function] The kind type parameter is that of |
| @code{pid}. |
| Returns 0 on success; otherwise a system-specific error code is returned. |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{ABORT}, @gol |
| @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}. It may be scalar or |
| array valued. |
| @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 90 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}, @gol |
| @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}, @gol |
| @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}, @gol |
| @ref{TRAILZ}, @gol |
| @ref{POPCNT}, @gol |
| @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 .23 .20 .33 |
| @headitem 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}, @gol |
| @ref{ADJUSTL}, @gol |
| @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 90 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}, @gol |
| @ref{ADJUSTL}, @gol |
| @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 .34 .16 .17 .30 |
| @headitem 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}, @gol |
| @ref{LLE}, @gol |
| @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 .34 .16 .17 .30 |
| @headitem 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}, @gol |
| @ref{LLE}, @gol |
| @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}, @gol |
| @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 .34 .16 .17 .30 |
| @headitem 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}, @gol |
| @ref{LGT}, @gol |
| @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 .34 .16 .17 .30 |
| @headitem 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}, @gol |
| @ref{LGT}, @gol |
| @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}, @gol |
| @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, has GNU extensions |
| |
| @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 < \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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later |
| @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later |
| @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later |
| @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later |
| @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 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 .23 .20 .33 |
| @headitem 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: @gol |
| @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 90 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}, @gol |
| @ref{REAL}, @gol |
| @ref{CMPLX} |
| @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. @var{SHIFT} shall be |
| nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise |
| the result 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}, @gol |
| @ref{ISHFTC}, @gol |
| @ref{RSHIFT}, @gol |
| @ref{SHIFTA}, @gol |
| @ref{SHIFTL}, @gol |
| @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: @gol |
| @ref{FSTAT} @gol |
| To stat a file: @gol |
| @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 @ref{TIME} |
| intrinsic), fills @var{VALUES} with values extracted from it appropriate |
| to the local time zone using @code{localtime(3)}. |
| |
| This intrinsic routine is provided for backwards compatibility with |
| GNU Fortran 77. In new code, programmers should consider the use of |
| the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 |
| standard. |
| |
| @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 1--31 |
| @item Number of months since January, range 0--11 |
| @item Years since 1900 |
| @item Number of days since Sunday, range 0--6 |
| @item Days since January 1, range 0--365 |
| @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{DATE_AND_TIME}, @gol |
| @ref{CTIME}, @gol |
| @ref{GMTIME}, @gol |
| @ref{TIME}, @gol |
| @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 90 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}. |
| @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays. |
| @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. |
| @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 .23 .20 .33 |
| @headitem 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} @gol |
| @ref{MAXVAL}, @gol |
| @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 90 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 |
| @var{BACK} is not present, or is false; if @var{BACK} is true, the location |
| returned is that of the last such element. 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; @var{ARRAY} of @code{CHARACTER} and the |
| @var{KIND} argument are available in Fortran 2003 and later. |
| The @var{BACK} argument is available in Fortran 2008 and later. |
| |
| @item @emph{Class}: |
| Transformational function |
| |
| @item @emph{Syntax}: |
| @multitable @columnfractions .80 |
| @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} |
| @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])} |
| @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 of type @code{LOGICAL}, |
| and conformable with @var{ARRAY}. |
| @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization |
| expression indicating the kind parameter of the result. |
| @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. |
| @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. If the optional argument @var{KIND} |
| is present, the result is an integer of kind @var{KIND}, otherwise it |
| is of default kind. |
| |
| @item @emph{See also}: |
| @ref{FINDLOC}, @gol |
| @ref{MAX}, @gol |
| @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 90 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 (Optional) Shall be 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}, @gol |
| @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}, @gol |
| @ref{GMTIME}, @gol |
| @ref{LTIME}, @gol |
| @ref{MCLOCK}, @gol |
| @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}, @gol |
| @ref{GMTIME}, @gol |
| @ref{LTIME}, @gol |
| @ref{MCLOCK}, @gol |
| @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 90 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} or a boz-literal-constant. |
| @item @var{J} @tab Shall be of type @code{INTEGER} with the same |
| kind type parameter as @var{I} or a boz-literal-constant. |
| @var{I} and @var{J} shall not both be boz-literal-constants. |
| @item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant |
| 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 minimum value among the arguments, |
| and has the same type and kind as the first argument. |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem 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}, @gol |
| @ref{MINLOC}, @gol |
| @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 90 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 |
| @var{BACK} is not present, or is false; if @var{BACK} is true, the location |
| returned is that of the last such element. 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 90 and later; @var{ARRAY} of @code{CHARACTER} and the |
| @var{KIND} argument are available in Fortran 2003 and later. |
| The @var{BACK} argument is available in Fortran 2008 and later. |
| |
| @item @emph{Class}: |
| Transformational function |
| |
| @item @emph{Syntax}: |
| @multitable @columnfractions .80 |
| @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} |
| @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])} |
| @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{CHARACTER}. |
| @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 of type @code{LOGICAL}, |
| and conformable with @var{ARRAY}. |
| @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization |
| expression indicating the kind parameter of the result. |
| @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. |
| @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. If the optional argument @var{KIND} |
| is present, the result is an integer of kind @var{KIND}, otherwise it |
| is of default kind. |
| |
| @item @emph{See also}: |
| @ref{FINDLOC}, @gol |
| @ref{MIN}, @gol |
| @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 90 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 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}, @gol |
| @ref{MINLOC} |
| @end table |
| |
| |
| |
| @node MOD |
| @section @code{MOD} --- Remainder function |
| @fnindex MOD |
| @fnindex AMOD |
| @fnindex DMOD |
| @fnindex BMOD |
| @fnindex IMOD |
| @fnindex JMOD |
| @fnindex KMOD |
| @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, has overloads that are GNU extensions |
| |
| @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. (As a GNU extension, arguments of different kinds are |
| permitted.) |
| @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. (As a GNU extension, kind is the largest kind of the actual |
| arguments.) |
| |
| @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 .25 .20 .31 |
| @headitem Name @tab Arguments @tab Return type @tab Standard |
| @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later |
| @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later |
| @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later |
| @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension |
| @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. (As a GNU extension, arguments of different kinds are |
| permitted.) |
| @end multitable |
| |
| @item @emph{Return value}: |
| The type and kind of the result are those of the arguments. (As a GNU |
| extension, kind is the largest kind of the actual 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 |
| @fnindex BMVBITS |
| @fnindex IMVBITS |
| @fnindex JMVBITS |
| @fnindex KMVBITS |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later |
| @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{IBCLR}, @gol |
| @ref{IBSET}, @gol |
| @ref{IBITS}, @gol |
| @ref{IAND}, @gol |
| @ref{IOR}, @gol |
| @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 90 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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return Type @tab Standard |
| @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later |
| @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{CEILING}, @gol |
| @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 @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 |
| @fnindex BNOT |
| @fnindex INOT |
| @fnindex JNOT |
| @fnindex KNOT |
| @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 90 and later, has overloads that are GNU extensions |
| |
| @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{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later |
| @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension |
| @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension |
| @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension |
| @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| @ref{IAND}, @gol |
| @ref{IEOR}, @gol |
| @ref{IOR}, @gol |
| @ref{IBITS}, @gol |
| @ref{IBSET}, @gol |
| @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. With @var{DISTANCE} or @var{FAILED} argument, |
| Technical Specification (TS) 18508 or later |
| |
| |
| @item @emph{Class}: |
| Transformational function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer |
| @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression |
| @end multitable |
| |
| @item @emph{Return value}: |
| Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, |
| the number of images in the current team is returned. For values smaller or |
| equal distance to the initial team, it returns the number of images index |
| on the ancestor team which has a distance of @var{DISTANCE} from the invoking |
| team. If @var{DISTANCE} is larger than the distance to the initial team, the |
| number of images of the initial team is returned. If @var{FAILED} is not present |
| the total number of images is returned; if it has the value @code{.TRUE.}, |
| the number of failed images is returned, otherwise, the number of images which |
| do have not the failed status. |
| |
| @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}, @gol |
| @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 or a boz-literal-constant. |
| @item @var{J} @tab The type shall be the same as the type of @var{I} or |
| a boz-literal-constant. @var{I} and @var{J} shall not both be |
| boz-literal-constants. If either @var{I} and @var{J} is a |
| boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. |
| @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. A boz-literal-constant is |
| converted to an @code{INTEGER} with the kind type parameter of |
| the other argument as-if a call to @ref{INT} occurred. |
| |
| @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: @gol |
| @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 90 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 /) |
| ! The following results in "1 2 3 4" |
| WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 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{MASK} @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{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 |
| @item @emph{See also}: |
| @ref{POPPAR}, @gol |
| @ref{LEADZ}, @gol |
| @ref{TRAILZ} |
| @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{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 |
| @item @emph{See also}: |
| @ref{POPCNT}, @gol |
| @ref{LEADZ}, @gol |
| @ref{TRAILZ} |
| @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 90 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}. It may |
| be scalar or valued. |
| @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 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 |
| @item @emph{See also}: |
| @ref{SELECTED_REAL_KIND}, @gol |
| @ref{RANGE} |
| @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 90 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 90 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 90 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{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 |
| @item @emph{See also}: |
| @ref{SELECTED_REAL_KIND} |
| @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}, @gol |
| @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}, @gol |
| @ref{RANDOM_NUMBER} |
| |
| @end table |
| |
| |
| @node RANDOM_INIT |
| @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator |
| @fnindex RANDOM_INIT |
| @cindex random number generation, initialization |
| |
| @table @asis |
| @item @emph{Description}: |
| Initializes the state of the pseudorandom number generator used by |
| @code{RANDOM_NUMBER}. |
| |
| @item @emph{Standard}: |
| Fortran 2018 |
| |
| @item @emph{Class}: |
| Subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .25 .70 |
| @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type, |
| and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to |
| a processor-dependent value that is the same each time @code{RANDOM_INIT} |
| is called from the same image. The term ``same image'' means a single |
| instance of program execution. The sequence of random numbers is different |
| for repeated execution of the program. If it is @code{.false.}, the seed |
| is set to a processor-dependent value. |
| @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a |
| @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.}, |
| the seed is set to a processor-dependent value that is distinct from th |
| seed set by a call to @code{RANDOM_INIT} in another image. If it is |
| @code{.false.}, the seed is set to a value that does depend which image called |
| @code{RANDOM_INIT}. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_random_seed |
| implicit none |
| real x(3), y(3) |
| call random_init(.true., .true.) |
| call random_number(x) |
| call random_init(.true., .true.) |
| call random_number(y) |
| ! x and y are the same sequence |
| if (any(x /= y)) call abort |
| end program test_random_seed |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{RANDOM_NUMBER}, @gol |
| @ref{RANDOM_SEED} |
| @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 the xoshiro256** pseudorandom number |
| generator (PRNG). This generator has a period of @math{2^{256} - 1}, |
| and when using multiple threads up to @math{2^{128}} threads can each |
| generate @math{2^{128}} random numbers before any aliasing occurs. |
| |
| Note that in a multi-threaded program (e.g. using OpenMP directives), |
| each thread will have its own random number state. For details of the |
| seeding procedure, see the documentation for the @code{RANDOM_SEED} |
| intrinsic. |
| |
| |
| @item @emph{Standard}: |
| Fortran 90 and later |
| |
| @item @emph{Class}: |
| Subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL 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 RANDOM_NUMBER(r) |
| end program |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{RANDOM_SEED}, @gol |
| @ref{RANDOM_INIT} |
| @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 seeded with |
| random data retrieved from the operating system. |
| |
| As an extension to the Fortran standard, the GFortran |
| @code{RANDOM_NUMBER} supports multiple threads. Each thread in a |
| multi-threaded program has its own seed. When @code{RANDOM_SEED} is |
| called either without arguments or with the @var{PUT} argument, the |
| given seed is copied into a master seed as well as the seed of the |
| current thread. When a new thread uses @code{RANDOM_NUMBER} for the |
| first time, the seed is copied from the master seed, and forwarded |
| @math{N * 2^{128}} steps to guarantee that the random stream does not |
| alias any other stream in the system, where @var{N} is the number of |
| threads that have used @code{RANDOM_NUMBER} so far during the program |
| execution. |
| |
| @item @emph{Standard}: |
| Fortran 90 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 |
| program test_random_seed |
| implicit none |
| integer, allocatable :: seed(:) |
| integer :: n |
| |
| call random_seed(size = n) |
| allocate(seed(n)) |
| call random_seed(get=seed) |
| write (*, *) seed |
| end program test_random_seed |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{RANDOM_NUMBER}, @gol |
| @ref{RANDOM_INIT} |
| @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 90 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{Example}: |
| See @code{PRECISION} for an example. |
| @item @emph{See also}: |
| @ref{SELECTED_REAL_KIND}, @gol |
| @ref{PRECISION} |
| @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 = RANK(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 2 |
| 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 FLOATI |
| @fnindex FLOATJ |
| @fnindex FLOATK |
| @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, with @var{KIND} argument Fortran 90 and later, has GNU extensions |
| |
| @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 .23 .20 .33 |
| @headitem 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{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension (-fdec) |
| @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension (-fdec) |
| @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension (-fdec) |
| @item @code{SNGL(A)} @tab @code{REAL(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 90 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 90 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 90 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. @var{SHIFT} shall be |
| nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise |
| the result 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}, @gol |
| @ref{ISHFTC}, @gol |
| @ref{LSHIFT}, @gol |
| @ref{SHIFTA}, @gol |
| @ref{SHIFTR}, @gol |
| @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 90 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 90 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}, @gol |
| @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 90 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 90 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{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 |
| @item @emph{See also}: |
| @ref{PRECISION}, @gol |
| @ref{RANGE}, @gol |
| @ref{RADIX} |
| @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 of @var{X} and whose exponent part is @var{I}. |
| |
| @item @emph{Standard}: |
| Fortran 90 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 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 90 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}, @gol |
| @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. @var{SHIFT} that be |
| nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise |
| the result 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}, @gol |
| @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. @var{SHIFT} shall be |
| nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise |
| the result 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}, @gol |
| @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. @var{SHIFT} shall be |
| nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise |
| the result 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}, @gol |
| @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 .26 .20 .30 |
| @headitem Name @tab Arguments @tab Return type @tab Standard |
| @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later |
| @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later |
| @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later |
| @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later |
| @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later |
| @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{ASIN} @gol |
| Degrees function: @gol |
| @ref{SIND} |
| @end table |
| |
| |
| |
| @node SIND |
| @section @code{SIND} --- Sine function, degrees |
| @fnindex SIND |
| @fnindex DSIND |
| @fnindex CSIND |
| @fnindex ZSIND |
| @fnindex CDSIND |
| @cindex trigonometric function, sine, degrees |
| @cindex sine, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{SIND(X)} computes the sine of @var{X} in degrees. |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = SIND(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}, and its value is in degrees. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_sind |
| real :: x = 0.0 |
| x = sind(x) |
| end program test_sind |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension |
| @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{ASIND} @gol |
| Radians function: @gol |
| @ref{SIN} @gol |
| @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 90 and later, for a complex argument Fortran 2008 or later, has |
| a GNU extension |
| |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 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 90 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}, @gol |
| @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}: |
| Inquiry 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 dynamic type is returned. The argument |
| may not be a procedure or procedure pointer. Note that the code assumes for |
| arrays that those are contiguous; for contiguous arrays, it returns the |
| storage or an array element multiplied by the size of the array. |
| |
| @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}, @gol |
| @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 90 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 90 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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later |
| @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later |
| @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 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 standard specifies the intrinsic subroutines |
| @code{RANDOM_SEED} to initialize the pseudo-random number |
| generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers. |
| These subroutines should be used in new codes. |
| |
| 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}, @gol |
| @ref{RANDOM_SEED}, @gol |
| @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: @gol |
| @ref{FSTAT} @gol |
| To stat a link: @gol |
| @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}, @gol |
| @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 90 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}, @gol |
| @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 |
| monotonic clock, that clock is used and can, depending on the platform |
| clock implementation, provide up to nanosecond resolution. If a |
| monotonic clock is not available, the implementation falls back to a |
| realtime clock. |
| |
| @var{COUNT_RATE} is system dependent and can vary depending on the kind of |
| the arguments. For @var{kind=4} arguments (and smaller integer kinds), |
| @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and |
| larger integer kinds), @var{COUNT} typically represents micro- or |
| nanoseconds depending on resolution of the underlying platform clock. |
| @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the |
| millisecond resolution of the @var{kind=4} version implies that the |
| @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues |
| with the wrap around and for more precise timing, please use the |
| @var{kind=8} version. |
| |
| If there is no clock, or querying the clock fails, @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) version |
| 2.16 or older, 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. |
| |
| On the Windows platform, the version with @var{kind=4} arguments uses |
| the @code{GetTickCount} function, whereas the @var{kind=8} version |
| uses @code{QueryPerformanceCounter} and |
| @code{QueryPerformanceCounterFrequency}. For more information, and |
| potential caveats, please see the platform documentation. |
| |
| @item @emph{Standard}: |
| Fortran 90 and later |
| |
| @item @emph{Class}: |
| Subroutine |
| |
| @item @emph{Syntax}: |
| @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .20 .65 |
| @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} or @code{REAL}, 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}, @gol |
| @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}, and its value is in radians. |
| |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later |
| @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{ATAN} @gol |
| Degrees function: @gol |
| @ref{TAND} |
| @end table |
| |
| |
| |
| @node TAND |
| @section @code{TAND} --- Tangent function, degrees |
| @fnindex TAND |
| @fnindex DTAND |
| @cindex trigonometric function, tangent, degrees |
| @cindex tangent, degrees |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{TAND(X)} computes the tangent of @var{X} in degrees. |
| |
| This function is for compatibility only and should be avoided in favor of |
| standard constructs wherever possible. |
| |
| @item @emph{Standard}: |
| GNU extension, enabled with @option{-fdec-math}. |
| |
| @item @emph{Class}: |
| Elemental function |
| |
| @item @emph{Syntax}: |
| @code{RESULT = TAND(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}, and its value is in degrees. |
| |
| @item @emph{Example}: |
| @smallexample |
| program test_tand |
| real(8) :: x = 0.165_8 |
| x = tand(x) |
| end program test_tand |
| @end smallexample |
| |
| @item @emph{Specific names}: |
| @multitable @columnfractions .20 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension |
| @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension |
| @end multitable |
| |
| @item @emph{See also}: |
| Inverse function: @gol |
| @ref{ATAND} @gol |
| Radians function: @gol |
| @ref{TAN} |
| @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 .23 .20 .33 |
| @headitem Name @tab Argument @tab Return type @tab Standard |
| @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later |
| @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 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. With @var{DISTANCE} argument, |
| Technical Specification (TS) 18508 or later |
| |
| @item @emph{Class}: |
| Transformational function |
| |
| @item @emph{Syntax}: |
| @multitable @columnfractions .80 |
| @item @code{RESULT = THIS_IMAGE()} |
| @item @code{RESULT = THIS_IMAGE(DISTANCE)} |
| @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} |
| @end multitable |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer |
| (not permitted together with @var{COARRAY}). |
| @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; if |
| @var{DISTANCE} is not present or has value 0, its value is the image index on |
| the invoking image for the current team, for values smaller or equal |
| distance to the initial team, it returns the image index on the ancestor team |
| which has a distance of @var{DISTANCE} from the invoking team. If |
| @var{DISTANCE} is larger than the distance to the initial team, the image |
| index of the initial team is returned. Otherwise when the @var{COARRAY} is |
| present, 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 |
| |
| ! Check whether the current image is the initial image |
| IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) |
| error stop "something is rotten here" |
| @end smallexample |
| |
| @item @emph{See also}: |
| @ref{NUM_IMAGES}, @gol |
| @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 @ref{CTIME}, @ref{GMTIME}, and @ref{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{DATE_AND_TIME}, @gol |
| @ref{CTIME}, @gol |
| @ref{GMTIME}, @gol |
| @ref{LTIME}, @gol |
| @ref{MCLOCK}, @gol |
| @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 @ref{CTIME}, @ref{GMTIME}, and @ref{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{DATE_AND_TIME}, @gol |
| @ref{CTIME}, @gol |
| @ref{GMTIME}, @gol |
| @ref{LTIME}, @gol |
| @ref{MCLOCK8}, @gol |
| @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 90 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}, @gol |
| @ref{LEADZ}, @gol |
| @ref{POPPAR}, @gol |
| @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 90 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 90 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 90 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}, @gol |
| @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 90 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}, @gol |
| @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}, @gol |
| @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}, @gol |
| @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 90 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}, @gol |
| @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 90 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}, @gol |
| @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 or a boz-literal-constant. |
| @item @var{J} @tab The type shall be the same as the type of @var{I} or |
| a boz-literal-constant. @var{I} and @var{J} shall not both be |
| boz-literal-constants. If either @var{I} and @var{J} is a |
| boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. |
| @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. A boz-literal-constant is |
| converted to an @code{INTEGER} with the kind type parameter of |
| the other argument as-if a call to @ref{INT} occurred. |
| |
| @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: @gol |
| @ref{IEOR} |
| @end table |
| |
| |
| |
| @node Intrinsic Modules |
| @chapter Intrinsic Modules |
| @cindex intrinsic Modules |
| |
| @menu |
| * ISO_FORTRAN_ENV:: |
| * ISO_C_BINDING:: |
| * IEEE modules:: |
| * OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: |
| * OpenACC Module OPENACC:: |
| @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_FAILED_IMAGE}: |
| Positive, scalar default-integer constant used as STAT= return value if the |
| argument in the statement requires communication with an image, which has |
| is in the failed state. (TS 18508 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} and @code{C_FLOAT128_COMPLEX} are defined. |
| |
| @multitable @columnfractions .19 .32 .34 .15 |
| @headitem 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{ptrdiff_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{COMPLEX}@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 |
| @headitem 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 |
| @headitem 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 IEEE modules |
| @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} |
| @table @asis |
| @item @emph{Standard}: |
| Fortran 2003 and later |
| @end table |
| |
| The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} |
| intrinsic modules provide support for exceptions and IEEE arithmetic, as |
| defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard |
| (@emph{Binary floating-point arithmetic for microprocessor systems}). These |
| modules are only provided on the following supported platforms: |
| |
| @itemize @bullet |
| @item i386 and x86_64 processors |
| @item platforms which use the GNU C Library (glibc) |
| @item platforms with support for SysV/386 routines for floating point |
| interface (including Solaris and BSDs) |
| @item platforms with the AIX OS |
| @end itemize |
| |
| For full compliance with the Fortran standards, code using the |
| @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled |
| with the following options: @code{-fno-unsafe-math-optimizations |
| -frounding-math -fsignaling-nans}. |
| |
| |
| |
| @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 v4.5, |
| OpenMP Application Program Interface v5.0 (partially supported) and |
| OpenMP Application Program Interface v5.1 (partially supported). |
| @end table |
| |
| The OpenMP Fortran runtime library routines are provided both in |
| a form of two Fortran 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 Offloading and Multi |
| Processing Runtime Library} manual, |
| the named constants defined in the modules are listed |
| below. |
| |
| For details refer to the actual |
| @uref{https://www.openmp.org/wp-content/uploads/openmp-4.5.pdf, |
| OpenMP Application Program Interface v4.5} and |
| @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf, |
| OpenMP Application Program Interface v5.0}. |
| |
| @code{OMP_LIB_KINDS} provides the following scalar default-integer |
| named constants: |
| |
| @table @asis |
| @item @code{omp_allocator_handle_kind} |
| @item @code{omp_alloctrait_key_kind} |
| @item @code{omp_alloctrait_val_kind} |
| @item @code{omp_depend_kind} |
| @item @code{omp_lock_kind} |
| @item @code{omp_lock_hint_kind} |
| @item @code{omp_nest_lock_kind} |
| @item @code{omp_pause_resource_kind} |
| @item @code{omp_memspace_handle_kind} |
| @item @code{omp_proc_bind_kind} |
| @item @code{omp_sched_kind} |
| @item @code{omp_sync_hint_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 v4.5 the value is @code{201511}. |
| |
| The following derived type: |
| |
| @table @asis |
| @item @code{omp_alloctrait} |
| @end table |
| |
| 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 |
| |
| And the following scalar integer named constants of the |
| kind @code{omp_proc_bind_kind}: |
| |
| @table @asis |
| @item @code{omp_proc_bind_false} |
| @item @code{omp_proc_bind_true} |
| @item @code{omp_proc_bind_primary} |
| @item @code{omp_proc_bind_master} |
| @item @code{omp_proc_bind_close} |
| @item @code{omp_proc_bind_spread} |
| @end table |
| |
| The following scalar integer named constants are of the |
| kind @code{omp_lock_hint_kind}: |
| |
| @table @asis |
| @item @code{omp_lock_hint_none} |
| @item @code{omp_lock_hint_uncontended} |
| @item @code{omp_lock_hint_contended} |
| @item @code{omp_lock_hint_nonspeculative} |
| @item @code{omp_lock_hint_speculative} |
| @item @code{omp_sync_hint_none} |
| @item @code{omp_sync_hint_uncontended} |
| @item @code{omp_sync_hint_contended} |
| @item @code{omp_sync_hint_nonspeculative} |
| @item @code{omp_sync_hint_speculative} |
| @end table |
| |
| And the following two scalar integer named constants are of the |
| kind @code{omp_pause_resource_kind}: |
| |
| @table @asis |
| @item @code{omp_pause_soft} |
| @item @code{omp_pause_hard} |
| @end table |
| |
| The following scalar integer named constants are of the kind |
| @code{omp_alloctrait_key_kind}: |
| |
| @table @asis |
| @item @code{omp_atk_sync_hint} |
| @item @code{omp_atk_alignment} |
| @item @code{omp_atk_access} |
| @item @code{omp_atk_pool_size} |
| @item @code{omp_atk_fallback} |
| @item @code{omp_atk_fb_data} |
| @item @code{omp_atk_pinned} |
| @item @code{omp_atk_partition} |
| @end table |
| |
| The following scalar integer named constants are of the kind |
| @code{omp_alloctrait_val_kind}: |
| |
| @table @asis |
| @code{omp_alloctrait_key_kind}: |
| @item @code{omp_atv_default} |
| @item @code{omp_atv_false} |
| @item @code{omp_atv_true} |
| @item @code{omp_atv_contended} |
| @item @code{omp_atv_uncontended} |
| @item @code{omp_atv_serialized} |
| @item @code{omp_atv_sequential} |
| @item @code{omp_atv_private} |
| @item @code{omp_atv_all} |
| @item @code{omp_atv_thread} |
| @item @code{omp_atv_pteam} |
| @item @code{omp_atv_cgroup} |
| @item @code{omp_atv_default_mem_fb} |
| @item @code{omp_atv_null_fb} |
| @item @code{omp_atv_abort_fb} |
| @item @code{omp_atv_allocator_fb} |
| @item @code{omp_atv_environment} |
| @item @code{omp_atv_nearest} |
| @item @code{omp_atv_blocked} |
| @end table |
| |
| The following scalar integer named constants are of the kind |
| @code{omp_allocator_handle_kind}: |
| |
| @table @asis |
| @item @code{omp_null_allocator} |
| @item @code{omp_default_mem_alloc} |
| @item @code{omp_large_cap_mem_alloc} |
| @item @code{omp_const_mem_alloc} |
| @item @code{omp_high_bw_mem_alloc} |
| @item @code{omp_low_lat_mem_alloc} |
| @item @code{omp_cgroup_mem_alloc} |
| @item @code{omp_pteam_mem_alloc} |
| @item @code{omp_thread_mem_alloc} |
| @end table |
| |
| The following scalar integer named constants are of the kind |
| @code{omp_memspace_handle_kind}: |
| |
| @table @asis |
| @item @code{omp_default_mem_space} |
| @item @code{omp_large_cap_mem_space} |
| @item @code{omp_const_mem_space} |
| @item @code{omp_high_bw_mem_space} |
| @item @code{omp_low_lat_mem_space} |
| @end table |
| |
| |
| |
| @node OpenACC Module OPENACC |
| @section OpenACC Module @code{OPENACC} |
| @table @asis |
| @item @emph{Standard}: |
| OpenACC Application Programming Interface v2.6 |
| @end table |
| |
| |
| The OpenACC Fortran runtime library routines are provided both in a |
| form of a Fortran 90 module, named @code{OPENACC}, and in form of a |
| Fortran @code{include} file named @file{openacc_lib.h}. The |
| procedures provided by @code{OPENACC} can be found in the |
| @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing |
| Runtime Library} manual, the named constants defined in the modules |
| are listed below. |
| |
| For details refer to the actual |
| @uref{https://www.openacc.org/, |
| OpenACC Application Programming Interface v2.6}. |
| |
| @code{OPENACC} provides the scalar default-integer |
| named constant @code{openacc_version} with a value of the form |
| @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month |
| of the OpenACC version; for OpenACC v2.6 the value is @code{201711}. |
