Mercurial > hg > CbC > CbC_llvm
comparison flang/docs/Intrinsics.md @ 221:79ff65ed7e25
LLVM12 Original
| author | Shinji KONO <kono@ie.u-ryukyu.ac.jp> |
|---|---|
| date | Tue, 15 Jun 2021 19:15:29 +0900 |
| parents | |
| children | c4bab56944e8 |
comparison
equal
deleted
inserted
replaced
| 220:42394fc6a535 | 221:79ff65ed7e25 |
|---|---|
| 1 <!--===- docs/Intrinsics.md | |
| 2 | |
| 3 Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. | |
| 4 See https://llvm.org/LICENSE.txt for license information. | |
| 5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception | |
| 6 | |
| 7 --> | |
| 8 | |
| 9 # A categorization of standard (2018) and extended Fortran intrinsic procedures | |
| 10 | |
| 11 ```eval_rst | |
| 12 .. contents:: | |
| 13 :local: | |
| 14 ``` | |
| 15 | |
| 16 This note attempts to group the intrinsic procedures of Fortran into categories | |
| 17 of functions or subroutines with similar interfaces as an aid to | |
| 18 comprehension beyond that which might be gained from the standard's | |
| 19 alphabetical list. | |
| 20 | |
| 21 A brief status of intrinsic procedure support in f18 is also given at the end. | |
| 22 | |
| 23 Few procedures are actually described here apart from their interfaces; see the | |
| 24 Fortran 2018 standard (section 16) for the complete story. | |
| 25 | |
| 26 Intrinsic modules are not covered here. | |
| 27 | |
| 28 ## General rules | |
| 29 | |
| 30 1. The value of any intrinsic function's `KIND` actual argument, if present, | |
| 31 must be a scalar constant integer expression, of any kind, whose value | |
| 32 resolves to some supported kind of the function's result type. | |
| 33 If optional and absent, the kind of the function's result is | |
| 34 either the default kind of that category or to the kind of an argument | |
| 35 (e.g., as in `AINT`). | |
| 36 1. Procedures are summarized with a non-Fortran syntax for brevity. | |
| 37 Wherever a function has a short definition, it appears after an | |
| 38 equal sign as if it were a statement function. Any functions referenced | |
| 39 in these short summaries are intrinsic. | |
| 40 1. Unless stated otherwise, an actual argument may have any supported kind | |
| 41 of a particular intrinsic type. Sometimes a pattern variable | |
| 42 can appear in a description (e.g., `REAL(k)`) when the kind of an | |
| 43 actual argument's type must match the kind of another argument, or | |
| 44 determines the kind type parameter of the function result. | |
| 45 1. When an intrinsic type name appears without a kind (e.g., `REAL`), | |
| 46 it refers to the default kind of that type. Sometimes the word | |
| 47 `default` will appear for clarity. | |
| 48 1. The names of the dummy arguments actually matter because they can | |
| 49 be used as keywords for actual arguments. | |
| 50 1. All standard intrinsic functions are pure, even when not elemental. | |
| 51 1. Assumed-rank arguments may not appear as actual arguments unless | |
| 52 expressly permitted. | |
| 53 1. When an argument is described with a default value, e.g. `KIND=KIND(0)`, | |
| 54 it is an optional argument. Optional arguments without defaults, | |
| 55 e.g. `DIM` on many transformationals, are wrapped in `[]` brackets | |
| 56 as in the Fortran standard. When an intrinsic has optional arguments | |
| 57 with and without default values, the arguments with default values | |
| 58 may appear within the brackets to preserve the order of arguments | |
| 59 (e.g., `COUNT`). | |
| 60 | |
| 61 ## Elemental intrinsic functions | |
| 62 | |
| 63 Pure elemental semantics apply to these functions, to wit: when one or more of | |
| 64 the actual arguments are arrays, the arguments must be conformable, and | |
| 65 the result is also an array. | |
| 66 Scalar arguments are expanded when the arguments are not all scalars. | |
| 67 | |
| 68 ### Elemental intrinsic functions that may have unrestricted specific procedures | |
| 69 | |
| 70 When an elemental intrinsic function is documented here as having an | |
| 71 _unrestricted specific name_, that name may be passed as an actual | |
| 72 argument, used as the target of a procedure pointer, appear in | |
| 73 a generic interface, and be otherwise used as if it were an external | |
| 74 procedure. | |
| 75 An `INTRINSIC` statement or attribute may have to be applied to an | |
| 76 unrestricted specific name to enable such usage. | |
| 77 | |
| 78 When a name is being used as a specific procedure for any purpose other | |
| 79 than that of a called function, the specific instance of the function | |
| 80 that accepts and returns values of the default kinds of the intrinsic | |
| 81 types is used. | |
| 82 A Fortran `INTERFACE` could be written to define each of | |
| 83 these unrestricted specific intrinsic function names. | |
| 84 | |
| 85 Calls to dummy arguments and procedure pointers that correspond to these | |
| 86 specific names must pass only scalar actual argument values. | |
| 87 | |
| 88 No other intrinsic function name can be passed as an actual argument, | |
| 89 used as a pointer target, appear in a generic interface, or be otherwise | |
| 90 used except as the name of a called function. | |
| 91 Some of these _restricted specific intrinsic functions_, e.g. `FLOAT`, | |
| 92 provide a means for invoking a corresponding generic (`REAL` in the case of `FLOAT`) | |
| 93 with forced argument and result kinds. | |
| 94 Others, viz. `CHAR`, `ICHAR`, `INT`, `REAL`, and the lexical comparisons like `LGE`, | |
| 95 have the same name as their generic functions, and it is not clear what purpose | |
| 96 is accomplished by the standard by defining them as specific functions. | |
| 97 | |
| 98 ### Trigonometric elemental intrinsic functions, generic and (mostly) specific | |
| 99 All of these functions can be used as unrestricted specific names. | |
| 100 | |
| 101 ``` | |
| 102 ACOS(REAL(k) X) -> REAL(k) | |
| 103 ASIN(REAL(k) X) -> REAL(k) | |
| 104 ATAN(REAL(k) X) -> REAL(k) | |
| 105 ATAN(REAL(k) Y, REAL(k) X) -> REAL(k) = ATAN2(Y, X) | |
| 106 ATAN2(REAL(k) Y, REAL(k) X) -> REAL(k) | |
| 107 COS(REAL(k) X) -> REAL(k) | |
| 108 COSH(REAL(k) X) -> REAL(k) | |
| 109 SIN(REAL(k) X) -> REAL(k) | |
| 110 SINH(REAL(k) X) -> REAL(k) | |
| 111 TAN(REAL(k) X) -> REAL(k) | |
| 112 TANH(REAL(k) X) -> REAL(k) | |
| 113 ``` | |
| 114 | |
| 115 These `COMPLEX` versions of some of those functions, and the | |
| 116 inverse hyperbolic functions, cannot be used as specific names. | |
| 117 ``` | |
| 118 ACOS(COMPLEX(k) X) -> COMPLEX(k) | |
| 119 ASIN(COMPLEX(k) X) -> COMPLEX(k) | |
| 120 ATAN(COMPLEX(k) X) -> COMPLEX(k) | |
| 121 ACOSH(REAL(k) X) -> REAL(k) | |
| 122 ACOSH(COMPLEX(k) X) -> COMPLEX(k) | |
| 123 ASINH(REAL(k) X) -> REAL(k) | |
| 124 ASINH(COMPLEX(k) X) -> COMPLEX(k) | |
| 125 ATANH(REAL(k) X) -> REAL(k) | |
| 126 ATANH(COMPLEX(k) X) -> COMPLEX(k) | |
| 127 COS(COMPLEX(k) X) -> COMPLEX(k) | |
| 128 COSH(COMPLEX(k) X) -> COMPLEX(k) | |
| 129 SIN(COMPLEX(k) X) -> COMPLEX(k) | |
| 130 SINH(COMPLEX(k) X) -> COMPLEX(k) | |
| 131 TAN(COMPLEX(k) X) -> COMPLEX(k) | |
| 132 TANH(COMPLEX(k) X) -> COMPLEX(k) | |
| 133 ``` | |
| 134 | |
| 135 ### Non-trigonometric elemental intrinsic functions, generic and specific | |
| 136 These functions *can* be used as unrestricted specific names. | |
| 137 ``` | |
| 138 ABS(REAL(k) A) -> REAL(k) = SIGN(A, 0.0) | |
| 139 AIMAG(COMPLEX(k) Z) -> REAL(k) = Z%IM | |
| 140 AINT(REAL(k) A, KIND=k) -> REAL(KIND) | |
| 141 ANINT(REAL(k) A, KIND=k) -> REAL(KIND) | |
| 142 CONJG(COMPLEX(k) Z) -> COMPLEX(k) = CMPLX(Z%RE, -Z%IM) | |
| 143 DIM(REAL(k) X, REAL(k) Y) -> REAL(k) = X-MIN(X,Y) | |
| 144 DPROD(default REAL X, default REAL Y) -> DOUBLE PRECISION = DBLE(X)*DBLE(Y) | |
| 145 EXP(REAL(k) X) -> REAL(k) | |
| 146 INDEX(CHARACTER(k) STRING, CHARACTER(k) SUBSTRING, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND) | |
| 147 LEN(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n | |
| 148 LOG(REAL(k) X) -> REAL(k) | |
| 149 LOG10(REAL(k) X) -> REAL(k) | |
| 150 MOD(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k) = A-P*INT(A/P) | |
| 151 NINT(REAL(k) A, KIND=KIND(0)) -> INTEGER(KIND) | |
| 152 SIGN(REAL(k) A, REAL(k) B) -> REAL(k) | |
| 153 SQRT(REAL(k) X) -> REAL(k) = X ** 0.5 | |
| 154 ``` | |
| 155 | |
| 156 These variants, however *cannot* be used as specific names without recourse to an alias | |
| 157 from the following section: | |
| 158 ``` | |
| 159 ABS(INTEGER(k) A) -> INTEGER(k) = SIGN(A, 0) | |
| 160 ABS(COMPLEX(k) A) -> REAL(k) = HYPOT(A%RE, A%IM) | |
| 161 DIM(INTEGER(k) X, INTEGER(k) Y) -> INTEGER(k) = X-MIN(X,Y) | |
| 162 EXP(COMPLEX(k) X) -> COMPLEX(k) | |
| 163 LOG(COMPLEX(k) X) -> COMPLEX(k) | |
| 164 MOD(REAL(k) A, REAL(k) P) -> REAL(k) = A-P*INT(A/P) | |
| 165 SIGN(INTEGER(k) A, INTEGER(k) B) -> INTEGER(k) | |
| 166 SQRT(COMPLEX(k) X) -> COMPLEX(k) | |
| 167 ``` | |
| 168 | |
| 169 ### Unrestricted specific aliases for some elemental intrinsic functions with distinct names | |
| 170 | |
| 171 ``` | |
| 172 ALOG(REAL X) -> REAL = LOG(X) | |
| 173 ALOG10(REAL X) -> REAL = LOG10(X) | |
| 174 AMOD(REAL A, REAL P) -> REAL = MOD(A, P) | |
| 175 CABS(COMPLEX A) = ABS(A) | |
| 176 CCOS(COMPLEX X) = COS(X) | |
| 177 CEXP(COMPLEX A) -> COMPLEX = EXP(A) | |
| 178 CLOG(COMPLEX X) -> COMPLEX = LOG(X) | |
| 179 CSIN(COMPLEX X) -> COMPLEX = SIN(X) | |
| 180 CSQRT(COMPLEX X) -> COMPLEX = SQRT(X) | |
| 181 CTAN(COMPLEX X) -> COMPLEX = TAN(X) | |
| 182 DABS(DOUBLE PRECISION A) -> DOUBLE PRECISION = ABS(A) | |
| 183 DACOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = ACOS(X) | |
| 184 DASIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ASIN(X) | |
| 185 DATAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN(X) | |
| 186 DATAN2(DOUBLE PRECISION Y, DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN2(Y, X) | |
| 187 DCOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = COS(X) | |
| 188 DCOSH(DOUBLE PRECISION X) -> DOUBLE PRECISION = COSH(X) | |
| 189 DDIM(DOUBLE PRECISION X, DOUBLE PRECISION Y) -> DOUBLE PRECISION = X-MIN(X,Y) | |
| 190 DEXP(DOUBLE PRECISION X) -> DOUBLE PRECISION = EXP(X) | |
| 191 DINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = AINT(A) | |
| 192 DLOG(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG(X) | |
| 193 DLOG10(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG10(X) | |
| 194 DMOD(DOUBLE PRECISION A, DOUBLE PRECISION P) -> DOUBLE PRECISION = MOD(A, P) | |
| 195 DNINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = ANINT(A) | |
| 196 DSIGN(DOUBLE PRECISION A, DOUBLE PRECISION B) -> DOUBLE PRECISION = SIGN(A, B) | |
| 197 DSIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = SIN(X) | |
| 198 DSINH(DOUBLE PRECISION X) -> DOUBLE PRECISION = SINH(X) | |
| 199 DSQRT(DOUBLE PRECISION X) -> DOUBLE PRECISION = SQRT(X) | |
| 200 DTAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = TAN(X) | |
| 201 DTANH(DOUBLE PRECISION X) -> DOUBLE PRECISION = TANH(X) | |
| 202 IABS(INTEGER A) -> INTEGER = ABS(A) | |
| 203 IDIM(INTEGER X, INTEGER Y) -> INTEGER = X-MIN(X,Y) | |
| 204 IDNINT(DOUBLE PRECISION A) -> INTEGER = NINT(A) | |
| 205 ISIGN(INTEGER A, INTEGER B) -> INTEGER = SIGN(A, B) | |
| 206 ``` | |
| 207 | |
| 208 ## Generic elemental intrinsic functions without specific names | |
| 209 | |
| 210 (No procedures after this point can be passed as actual arguments, used as | |
| 211 pointer targets, or appear as specific procedures in generic interfaces.) | |
| 212 | |
| 213 ### Elemental conversions | |
| 214 | |
| 215 ``` | |
| 216 ACHAR(INTEGER(k) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1) | |
| 217 CEILING(REAL() A, KIND=KIND(0)) -> INTEGER(KIND) | |
| 218 CHAR(INTEGER(any) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1) | |
| 219 CMPLX(COMPLEX(k) X, KIND=KIND(0.0D0)) -> COMPLEX(KIND) | |
| 220 CMPLX(INTEGER or REAL or BOZ X, INTEGER or REAL or BOZ Y=0, KIND=KIND((0,0))) -> COMPLEX(KIND) | |
| 221 DBLE(INTEGER or REAL or COMPLEX or BOZ A) = REAL(A, KIND=KIND(0.0D0)) | |
| 222 EXPONENT(REAL(any) X) -> default INTEGER | |
| 223 FLOOR(REAL(any) A, KIND=KIND(0)) -> INTEGER(KIND) | |
| 224 IACHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND) | |
| 225 ICHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND) | |
| 226 INT(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0)) -> INTEGER(KIND) | |
| 227 LOGICAL(LOGICAL(any) L, KIND=KIND(.TRUE.)) -> LOGICAL(KIND) | |
| 228 REAL(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0.0)) -> REAL(KIND) | |
| 229 ``` | |
| 230 | |
| 231 ### Other generic elemental intrinsic functions without specific names | |
| 232 N.B. `BESSEL_JN(N1, N2, X)` and `BESSEL_YN(N1, N2, X)` are categorized | |
| 233 below with the _transformational_ intrinsic functions. | |
| 234 | |
| 235 ``` | |
| 236 BESSEL_J0(REAL(k) X) -> REAL(k) | |
| 237 BESSEL_J1(REAL(k) X) -> REAL(k) | |
| 238 BESSEL_JN(INTEGER(n) N, REAL(k) X) -> REAL(k) | |
| 239 BESSEL_Y0(REAL(k) X) -> REAL(k) | |
| 240 BESSEL_Y1(REAL(k) X) -> REAL(k) | |
| 241 BESSEL_YN(INTEGER(n) N, REAL(k) X) -> REAL(k) | |
| 242 ERF(REAL(k) X) -> REAL(k) | |
| 243 ERFC(REAL(k) X) -> REAL(k) | |
| 244 ERFC_SCALED(REAL(k) X) -> REAL(k) | |
| 245 FRACTION(REAL(k) X) -> REAL(k) | |
| 246 GAMMA(REAL(k) X) -> REAL(k) | |
| 247 HYPOT(REAL(k) X, REAL(k) Y) -> REAL(k) = SQRT(X*X+Y*Y) without spurious overflow | |
| 248 IMAGE_STATUS(INTEGER(any) IMAGE [, scalar TEAM_TYPE TEAM ]) -> default INTEGER | |
| 249 IS_IOSTAT_END(INTEGER(any) I) -> default LOGICAL | |
| 250 IS_IOSTAT_EOR(INTEGER(any) I) -> default LOGICAL | |
| 251 LOG_GAMMA(REAL(k) X) -> REAL(k) | |
| 252 MAX(INTEGER(k) ...) -> INTEGER(k) | |
| 253 MAX(REAL(k) ...) -> REAL(k) | |
| 254 MAX(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...))) | |
| 255 MERGE(any type TSOURCE, same type FSOURCE, LOGICAL(any) MASK) -> type of FSOURCE | |
| 256 MIN(INTEGER(k) ...) -> INTEGER(k) | |
| 257 MIN(REAL(k) ...) -> REAL(k) | |
| 258 MIN(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...))) | |
| 259 MODULO(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k); P*result >= 0 | |
| 260 MODULO(REAL(k) A, REAL(k) P) -> REAL(k) = A - P*FLOOR(A/P) | |
| 261 NEAREST(REAL(k) X, REAL(any) S) -> REAL(k) | |
| 262 OUT_OF_RANGE(INTEGER(any) X, scalar INTEGER or REAL(k) MOLD) -> default LOGICAL | |
| 263 OUT_OF_RANGE(REAL(any) X, scalar REAL(k) MOLD) -> default LOGICAL | |
| 264 OUT_OF_RANGE(REAL(any) X, scalar INTEGER(any) MOLD, scalar LOGICAL(any) ROUND=.FALSE.) -> default LOGICAL | |
| 265 RRSPACING(REAL(k) X) -> REAL(k) | |
| 266 SCALE(REAL(k) X, INTEGER(any) I) -> REAL(k) | |
| 267 SET_EXPONENT(REAL(k) X, INTEGER(any) I) -> REAL(k) | |
| 268 SPACING(REAL(k) X) -> REAL(k) | |
| 269 ``` | |
| 270 | |
| 271 ### Restricted specific aliases for elemental conversions &/or extrema with default intrinsic types | |
| 272 | |
| 273 ``` | |
| 274 AMAX0(INTEGER ...) = REAL(MAX(...)) | |
| 275 AMAX1(REAL ...) = MAX(...) | |
| 276 AMIN0(INTEGER...) = REAL(MIN(...)) | |
| 277 AMIN1(REAL ...) = MIN(...) | |
| 278 DMAX1(DOUBLE PRECISION ...) = MAX(...) | |
| 279 DMIN1(DOUBLE PRECISION ...) = MIN(...) | |
| 280 FLOAT(INTEGER I) = REAL(I) | |
| 281 IDINT(DOUBLE PRECISION A) = INT(A) | |
| 282 IFIX(REAL A) = INT(A) | |
| 283 MAX0(INTEGER ...) = MAX(...) | |
| 284 MAX1(REAL ...) = INT(MAX(...)) | |
| 285 MIN0(INTEGER ...) = MIN(...) | |
| 286 MIN1(REAL ...) = INT(MIN(...)) | |
| 287 SNGL(DOUBLE PRECISION A) = REAL(A) | |
| 288 ``` | |
| 289 | |
| 290 ### Generic elemental bit manipulation intrinsic functions | |
| 291 Many of these accept a typeless "BOZ" literal as an actual argument. | |
| 292 It is interpreted as having the kind of intrinsic `INTEGER` type | |
| 293 as another argument, as if the typeless were implicitly wrapped | |
| 294 in a call to `INT()`. | |
| 295 When multiple arguments can be either `INTEGER` values or typeless | |
| 296 constants, it is forbidden for *all* of them to be typeless | |
| 297 constants if the result of the function is `INTEGER` | |
| 298 (i.e., only `BGE`, `BGT`, `BLE`, and `BLT` can have multiple | |
| 299 typeless arguments). | |
| 300 | |
| 301 ``` | |
| 302 BGE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL | |
| 303 BGT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL | |
| 304 BLE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL | |
| 305 BLT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL | |
| 306 BTEST(INTEGER(n1) I, INTEGER(n2) POS) -> default LOGICAL | |
| 307 DSHIFTL(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k) | |
| 308 DSHIFTL(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k) | |
| 309 DSHIFTR(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k) | |
| 310 DSHIFTR(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k) | |
| 311 IAND(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k) | |
| 312 IAND(BOZ I, INTEGER(k) J) -> INTEGER(k) | |
| 313 IBCLR(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k) | |
| 314 IBITS(INTEGER(k) I, INTEGER(n1) POS, INTEGER(n2) LEN) -> INTEGER(k) | |
| 315 IBSET(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k) | |
| 316 IEOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k) | |
| 317 IEOR(BOZ I, INTEGER(k) J) -> INTEGER(k) | |
| 318 IOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k) | |
| 319 IOR(BOZ I, INTEGER(k) J) -> INTEGER(k) | |
| 320 ISHFT(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k) | |
| 321 ISHFTC(INTEGER(k) I, INTEGER(n1) SHIFT, INTEGER(n2) SIZE=BIT_SIZE(I)) -> INTEGER(k) | |
| 322 LEADZ(INTEGER(any) I) -> default INTEGER | |
| 323 MASKL(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND) | |
| 324 MASKR(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND) | |
| 325 MERGE_BITS(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK))) | |
| 326 MERGE_BITS(BOZ I, INTEGER(k) J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK))) | |
| 327 NOT(INTEGER(k) I) -> INTEGER(k) | |
| 328 POPCNT(INTEGER(any) I) -> default INTEGER | |
| 329 POPPAR(INTEGER(any) I) -> default INTEGER = IAND(POPCNT(I), Z'1') | |
| 330 SHIFTA(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k) | |
| 331 SHIFTL(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k) | |
| 332 SHIFTR(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k) | |
| 333 TRAILZ(INTEGER(any) I) -> default INTEGER | |
| 334 ``` | |
| 335 | |
| 336 ### Character elemental intrinsic functions | |
| 337 See also `INDEX` and `LEN` above among the elemental intrinsic functions with | |
| 338 unrestricted specific names. | |
| 339 ``` | |
| 340 ADJUSTL(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n) | |
| 341 ADJUSTR(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n) | |
| 342 LEN_TRIM(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n | |
| 343 LGE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL | |
| 344 LGT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL | |
| 345 LLE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL | |
| 346 LLT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL | |
| 347 SCAN(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND) | |
| 348 VERIFY(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND) | |
| 349 ``` | |
| 350 | |
| 351 `SCAN` returns the index of the first (or last, if `BACK=.TRUE.`) character in `STRING` | |
| 352 that is present in `SET`, or zero if none is. | |
| 353 | |
| 354 `VERIFY` is essentially the opposite: it returns the index of the first (or last) character | |
| 355 in `STRING` that is *not* present in `SET`, or zero if all are. | |
| 356 | |
| 357 ## Transformational intrinsic functions | |
| 358 | |
| 359 This category comprises a large collection of intrinsic functions that | |
| 360 are collected together because they somehow transform their arguments | |
| 361 in a way that prevents them from being elemental. | |
| 362 All of them are pure, however. | |
| 363 | |
| 364 Some general rules apply to the transformational intrinsic functions: | |
| 365 | |
| 366 1. `DIM` arguments are optional; if present, the actual argument must be | |
| 367 a scalar integer of any kind. | |
| 368 1. When an optional `DIM` argument is absent, or an `ARRAY` or `MASK` | |
| 369 argument is a vector, the result of the function is scalar; otherwise, | |
| 370 the result is an array of the same shape as the `ARRAY` or `MASK` | |
| 371 argument with the dimension `DIM` removed from the shape. | |
| 372 1. When a function takes an optional `MASK` argument, it must be conformable | |
| 373 with its `ARRAY` argument if it is present, and the mask can be any kind | |
| 374 of `LOGICAL`. It can be scalar. | |
| 375 1. The type `numeric` here can be any kind of `INTEGER`, `REAL`, or `COMPLEX`. | |
| 376 1. The type `relational` here can be any kind of `INTEGER`, `REAL`, or `CHARACTER`. | |
| 377 1. The type `any` here denotes any intrinsic or derived type. | |
| 378 1. The notation `(..)` denotes an array of any rank (but not an assumed-rank array). | |
| 379 | |
| 380 ### Logical reduction transformational intrinsic functions | |
| 381 ``` | |
| 382 ALL(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k) | |
| 383 ANY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k) | |
| 384 COUNT(LOGICAL(any) MASK(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND) | |
| 385 PARITY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k) | |
| 386 ``` | |
| 387 | |
| 388 ### Numeric reduction transformational intrinsic functions | |
| 389 ``` | |
| 390 IALL(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k) | |
| 391 IANY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k) | |
| 392 IPARITY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k) | |
| 393 NORM2(REAL(k) X(..) [, DIM ]) -> REAL(k) | |
| 394 PRODUCT(numeric ARRAY(..) [, DIM, MASK ]) -> numeric | |
| 395 SUM(numeric ARRAY(..) [, DIM, MASK ]) -> numeric | |
| 396 ``` | |
| 397 | |
| 398 `NORM2` generalizes `HYPOT` by computing `SQRT(SUM(X*X))` while avoiding spurious overflows. | |
| 399 | |
| 400 ### Extrema reduction transformational intrinsic functions | |
| 401 ``` | |
| 402 MAXVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k) | |
| 403 MINVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k) | |
| 404 ``` | |
| 405 | |
| 406 ### Locational transformational intrinsic functions | |
| 407 When the optional `DIM` argument is absent, the result is an `INTEGER(KIND)` | |
| 408 vector whose length is the rank of `ARRAY`. | |
| 409 When the optional `DIM` argument is present, the result is an `INTEGER(KIND)` | |
| 410 array of rank `RANK(ARRAY)-1` and shape equal to that of `ARRAY` with | |
| 411 the dimension `DIM` removed. | |
| 412 | |
| 413 The optional `BACK` argument is a scalar LOGICAL value of any kind. | |
| 414 When present and `.TRUE.`, it causes the function to return the index | |
| 415 of the *last* occurence of the target or extreme value. | |
| 416 | |
| 417 For `FINDLOC`, `ARRAY` may have any of the five intrinsic types, and `VALUE` | |
| 418 must a scalar value of a type for which `ARRAY==VALUE` or `ARRAY .EQV. VALUE` | |
| 419 is an acceptable expression. | |
| 420 | |
| 421 ``` | |
| 422 FINDLOC(intrinsic ARRAY(..), scalar VALUE [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ]) | |
| 423 MAXLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ]) | |
| 424 MINLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ]) | |
| 425 ``` | |
| 426 | |
| 427 ### Data rearrangement transformational intrinsic functions | |
| 428 The optional `DIM` argument to these functions must be a scalar integer of | |
| 429 any kind, and it takes a default value of 1 when absent. | |
| 430 | |
| 431 ``` | |
| 432 CSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, DIM ]) -> same type/kind/shape as ARRAY | |
| 433 ``` | |
| 434 Either `SHIFT` is scalar or `RANK(SHIFT) == RANK(ARRAY) - 1` and `SHAPE(SHIFT)` is that of `SHAPE(ARRAY)` with element `DIM` removed. | |
| 435 | |
| 436 ``` | |
| 437 EOSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, BOUNDARY, DIM ]) -> same type/kind/shape as ARRAY | |
| 438 ``` | |
| 439 * `SHIFT` is scalar or `RANK(SHIFT) == RANK(ARRAY) - 1` and `SHAPE(SHIFT)` is that of `SHAPE(ARRAY)` with element `DIM` removed. | |
| 440 * If `BOUNDARY` is present, it must have the same type and parameters as `ARRAY`. | |
| 441 * If `BOUNDARY` is absent, `ARRAY` must be of an intrinsic type, and the default `BOUNDARY` is the obvious `0`, `' '`, or `.FALSE.` value of `KIND(ARRAY)`. | |
| 442 * If `BOUNDARY` is present, either it is scalar, or `RANK(BOUNDARY) == RANK(ARRAY) - 1` and `SHAPE(BOUNDARY)` is that of `SHAPE(ARRAY)` with element `DIM` | |
| 443 removed. | |
| 444 | |
| 445 ``` | |
| 446 PACK(any ARRAY(..), LOGICAL(any) MASK(..)) -> vector of same type and kind as ARRAY | |
| 447 ``` | |
| 448 * `MASK` is conformable with `ARRAY` and may be scalar. | |
| 449 * The length of the result vector is `COUNT(MASK)` if `MASK` is an array, else `SIZE(ARRAY)` if `MASK` is `.TRUE.`, else zero. | |
| 450 | |
| 451 ``` | |
| 452 PACK(any ARRAY(..), LOGICAL(any) MASK(..), any VECTOR(n)) -> vector of same type, kind, and size as VECTOR | |
| 453 ``` | |
| 454 * `MASK` is conformable with `ARRAY` and may be scalar. | |
| 455 * `VECTOR` has the same type and kind as `ARRAY`. | |
| 456 * `VECTOR` must not be smaller than result of `PACK` with no `VECTOR` argument. | |
| 457 * The leading elements of `VECTOR` are replaced with elements from `ARRAY` as | |
| 458 if `PACK` had been invoked without `VECTOR`. | |
| 459 | |
| 460 ``` | |
| 461 RESHAPE(any SOURCE(..), INTEGER(k) SHAPE(n) [, PAD(..), INTEGER(k2) ORDER(n) ]) -> SOURCE array with shape SHAPE | |
| 462 ``` | |
| 463 * If `ORDER` is present, it is a vector of the same size as `SHAPE`, and | |
| 464 contains a permutation. | |
| 465 * The element(s) of `PAD` are used to fill out the result once `SOURCE` | |
| 466 has been consumed. | |
| 467 | |
| 468 ``` | |
| 469 SPREAD(any SOURCE, DIM, scalar INTEGER(any) NCOPIES) -> same type as SOURCE, rank=RANK(SOURCE)+1 | |
| 470 TRANSFER(any SOURCE, any MOLD) -> scalar if MOLD is scalar, else vector; same type and kind as MOLD | |
| 471 TRANSFER(any SOURCE, any MOLD, scalar INTEGER(any) SIZE) -> vector(SIZE) of type and kind of MOLD | |
| 472 TRANSPOSE(any MATRIX(n,m)) -> matrix(m,n) of same type and kind as MATRIX | |
| 473 ``` | |
| 474 | |
| 475 The shape of the result of `SPREAD` is the same as that of `SOURCE`, with `NCOPIES` inserted | |
| 476 at position `DIM`. | |
| 477 | |
| 478 ``` | |
| 479 UNPACK(any VECTOR(n), LOGICAL(any) MASK(..), FIELD) -> type and kind of VECTOR, shape of MASK | |
| 480 ``` | |
| 481 `FIELD` has same type and kind as `VECTOR` and is conformable with `MASK`. | |
| 482 | |
| 483 ### Other transformational intrinsic functions | |
| 484 ``` | |
| 485 BESSEL_JN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0)) | |
| 486 BESSEL_YN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0)) | |
| 487 COMMAND_ARGUMENT_COUNT() -> scalar default INTEGER | |
| 488 DOT_PRODUCT(LOGICAL(k) VECTOR_A(n), LOGICAL(k) VECTOR_B(n)) -> LOGICAL(k) = ANY(VECTOR_A .AND. VECTOR_B) | |
| 489 DOT_PRODUCT(COMPLEX(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(CONJG(VECTOR_A) * VECTOR_B) | |
| 490 DOT_PRODUCT(INTEGER(any) or REAL(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(VECTOR_A * VECTOR_B) | |
| 491 MATMUL(numeric ARRAY_A(j), numeric ARRAY_B(j,k)) -> numeric vector(k) | |
| 492 MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k)) -> numeric vector(j) | |
| 493 MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k,m)) -> numeric matrix(j,m) | |
| 494 MATMUL(LOGICAL(n1) ARRAY_A(j), LOGICAL(n2) ARRAY_B(j,k)) -> LOGICAL vector(k) | |
| 495 MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k)) -> LOGICAL vector(j) | |
| 496 MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k,m)) -> LOGICAL matrix(j,m) | |
| 497 NULL([POINTER/ALLOCATABLE MOLD]) -> POINTER | |
| 498 REDUCE(any ARRAY(..), function OPERATION [, DIM, LOGICAL(any) MASK(..), IDENTITY, LOGICAL ORDERED=.FALSE. ]) | |
| 499 REPEAT(CHARACTER(k,n) STRING, INTEGER(any) NCOPIES) -> CHARACTER(k,n*NCOPIES) | |
| 500 SELECTED_CHAR_KIND('DEFAULT' or 'ASCII' or 'ISO_10646' or ...) -> scalar default INTEGER | |
| 501 SELECTED_INT_KIND(scalar INTEGER(any) R) -> scalar default INTEGER | |
| 502 SELECTED_REAL_KIND([scalar INTEGER(any) P, scalar INTEGER(any) R, scalar INTEGER(any) RADIX]) -> scalar default INTEGER | |
| 503 SHAPE(SOURCE, KIND=KIND(0)) -> INTEGER(KIND)(RANK(SOURCE)) | |
| 504 TRIM(CHARACTER(k,n) STRING) -> CHARACTER(k) | |
| 505 ``` | |
| 506 | |
| 507 The type and kind of the result of a numeric `MATMUL` is the same as would result from | |
| 508 a multiplication of an element of ARRAY_A and an element of ARRAY_B. | |
| 509 | |
| 510 The kind of the `LOGICAL` result of a `LOGICAL` `MATMUL` is the same as would result | |
| 511 from an intrinsic `.AND.` operation between an element of `ARRAY_A` and an element | |
| 512 of `ARRAY_B`. | |
| 513 | |
| 514 Note that `DOT_PRODUCT` with a `COMPLEX` first argument operates on its complex conjugate, | |
| 515 but that `MATMUL` with a `COMPLEX` argument does not. | |
| 516 | |
| 517 The `MOLD` argument to `NULL` may be omitted only in a context where the type of the pointer is known, | |
| 518 such as an initializer or pointer assignment statement. | |
| 519 | |
| 520 At least one argument must be present in a call to `SELECTED_REAL_KIND`. | |
| 521 | |
| 522 An assumed-rank array may be passed to `SHAPE`, and if it is associated with an assumed-size array, | |
| 523 the last element of the result will be -1. | |
| 524 | |
| 525 ### Coarray transformational intrinsic functions | |
| 526 ``` | |
| 527 FAILED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector | |
| 528 GET_TEAM([scalar INTEGER(?) LEVEL]) -> scalar TEAM_TYPE | |
| 529 IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n) [, scalar TEAM_TYPE TEAM ]) -> scalar default INTEGER | |
| 530 IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n), scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER | |
| 531 NUM_IMAGES([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER | |
| 532 NUM_IMAGES(scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER | |
| 533 STOPPED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector | |
| 534 TEAM_NUMBER([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER | |
| 535 THIS_IMAGE([COARRAY, DIM, scalar TEAM_TYPE TEAM]) -> default INTEGER | |
| 536 ``` | |
| 537 The result of `THIS_IMAGE` is a scalar if `DIM` is present or if `COARRAY` is absent, | |
| 538 and a vector whose length is the corank of `COARRAY` otherwise. | |
| 539 | |
| 540 ## Inquiry intrinsic functions | |
| 541 These are neither elemental nor transformational; all are pure. | |
| 542 | |
| 543 ### Type inquiry intrinsic functions | |
| 544 All of these functions return constants. | |
| 545 The value of the argument is not used, and may well be undefined. | |
| 546 ``` | |
| 547 BIT_SIZE(INTEGER(k) I(..)) -> INTEGER(k) | |
| 548 DIGITS(INTEGER or REAL X(..)) -> scalar default INTEGER | |
| 549 EPSILON(REAL(k) X(..)) -> scalar REAL(k) | |
| 550 HUGE(INTEGER(k) X(..)) -> scalar INTEGER(k) | |
| 551 HUGE(REAL(k) X(..)) -> scalar of REAL(k) | |
| 552 KIND(intrinsic X(..)) -> scalar default INTEGER | |
| 553 MAXEXPONENT(REAL(k) X(..)) -> scalar default INTEGER | |
| 554 MINEXPONENT(REAL(k) X(..)) -> scalar default INTEGER | |
| 555 NEW_LINE(CHARACTER(k,n) A(..)) -> scalar CHARACTER(k,1) = CHAR(10) | |
| 556 PRECISION(REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER | |
| 557 RADIX(INTEGER(k) or REAL(k) X(..)) -> scalar default INTEGER, always 2 | |
| 558 RANGE(INTEGER(k) or REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER | |
| 559 TINY(REAL(k) X(..)) -> scalar REAL(k) | |
| 560 ``` | |
| 561 | |
| 562 ### Bound and size inquiry intrinsic functions | |
| 563 The results are scalar when `DIM` is present, and a vector of length=(co)rank(`(CO)ARRAY`) | |
| 564 when `DIM` is absent. | |
| 565 ``` | |
| 566 LBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND) | |
| 567 LCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND) | |
| 568 SIZE(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND) | |
| 569 UBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND) | |
| 570 UCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND) | |
| 571 ``` | |
| 572 | |
| 573 Assumed-rank arrays may be used with `LBOUND`, `SIZE`, and `UBOUND`. | |
| 574 | |
| 575 ### Object characteristic inquiry intrinsic functions | |
| 576 ``` | |
| 577 ALLOCATED(any type ALLOCATABLE ARRAY) -> scalar default LOGICAL | |
| 578 ALLOCATED(any type ALLOCATABLE SCALAR) -> scalar default LOGICAL | |
| 579 ASSOCIATED(any type POINTER POINTER [, same type TARGET]) -> scalar default LOGICAL | |
| 580 COSHAPE(COARRAY, KIND=KIND(0)) -> INTEGER(KIND) vector of length corank(COARRAY) | |
| 581 EXTENDS_TYPE_OF(A, MOLD) -> default LOGICAL | |
| 582 IS_CONTIGUOUS(any data ARRAY(..)) -> scalar default LOGICAL | |
| 583 PRESENT(OPTIONAL A) -> scalar default LOGICAL | |
| 584 RANK(any data A) -> scalar default INTEGER = 0 if A is scalar, SIZE(SHAPE(A)) if A is an array, rank if assumed-rank | |
| 585 SAME_TYPE_AS(A, B) -> scalar default LOGICAL | |
| 586 STORAGE_SIZE(any data A, KIND=KIND(0)) -> INTEGER(KIND) | |
| 587 ``` | |
| 588 The arguments to `EXTENDS_TYPE_OF` must be of extensible derived types or be unlimited polymorphic. | |
| 589 | |
| 590 An assumed-rank array may be used with `IS_CONTIGUOUS` and `RANK`. | |
| 591 | |
| 592 ## Intrinsic subroutines | |
| 593 | |
| 594 (*TODO*: complete these descriptions) | |
| 595 | |
| 596 ### One elemental intrinsic subroutine | |
| 597 ``` | |
| 598 INTERFACE | |
| 599 SUBROUTINE MVBITS(FROM, FROMPOS, LEN, TO, TOPOS) | |
| 600 INTEGER(k1) :: FROM, TO | |
| 601 INTENT(IN) :: FROM | |
| 602 INTENT(INOUT) :: TO | |
| 603 INTEGER(k2), INTENT(IN) :: FROMPOS | |
| 604 INTEGER(k3), INTENT(IN) :: LEN | |
| 605 INTEGER(k4), INTENT(IN) :: TOPOS | |
| 606 END SUBROUTINE | |
| 607 END INTERFACE | |
| 608 ``` | |
| 609 | |
| 610 ### Non-elemental intrinsic subroutines | |
| 611 ``` | |
| 612 CALL CPU_TIME(REAL INTENT(OUT) TIME) | |
| 613 ``` | |
| 614 The kind of `TIME` is not specified in the standard. | |
| 615 | |
| 616 ``` | |
| 617 CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES]) | |
| 618 ``` | |
| 619 * All arguments are `OPTIONAL` and `INTENT(OUT)`. | |
| 620 * `DATE`, `TIME`, and `ZONE` are scalar default `CHARACTER`. | |
| 621 * `VALUES` is a vector of at least 8 elements of `INTEGER(KIND >= 2)`. | |
| 622 ``` | |
| 623 CALL EVENT_QUERY(EVENT, COUNT [, STAT]) | |
| 624 CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ]) | |
| 625 CALL GET_COMMAND([COMMAND, LENGTH, STATUS, ERRMSG ]) | |
| 626 CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS, ERRMSG ]) | |
| 627 CALL GET_ENVIRONMENT_VARIABLE(NAME [, VALUE, LENGTH, STATUS, TRIM_NAME, ERRMSG ]) | |
| 628 CALL MOVE_ALLOC(ALLOCATABLE INTENT(INOUT) FROM, ALLOCATABLE INTENT(OUT) TO [, STAT, ERRMSG ]) | |
| 629 CALL RANDOM_INIT(LOGICAL(k1) INTENT(IN) REPEATABLE, LOGICAL(k2) INTENT(IN) IMAGE_DISTINCT) | |
| 630 CALL RANDOM_NUMBER(REAL(k) INTENT(OUT) HARVEST(..)) | |
| 631 CALL RANDOM_SEED([SIZE, PUT, GET]) | |
| 632 CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX]) | |
| 633 ``` | |
| 634 | |
| 635 ### Atomic intrinsic subroutines | |
| 636 ``` | |
| 637 CALL ATOMIC_ADD(ATOM, VALUE [, STAT=]) | |
| 638 CALL ATOMIC_AND(ATOM, VALUE [, STAT=]) | |
| 639 CALL ATOMIC_CAS(ATOM, OLD, COMPARE, NEW [, STAT=]) | |
| 640 CALL ATOMIC_DEFINE(ATOM, VALUE [, STAT=]) | |
| 641 CALL ATOMIC_FETCH_ADD(ATOM, VALUE, OLD [, STAT=]) | |
| 642 CALL ATOMIC_FETCH_AND(ATOM, VALUE, OLD [, STAT=]) | |
| 643 CALL ATOMIC_FETCH_OR(ATOM, VALUE, OLD [, STAT=]) | |
| 644 CALL ATOMIC_FETCH_XOR(ATOM, VALUE, OLD [, STAT=]) | |
| 645 CALL ATOMIC_OR(ATOM, VALUE [, STAT=]) | |
| 646 CALL ATOMIC_REF(VALUE, ATOM [, STAT=]) | |
| 647 CALL ATOMIC_XOR(ATOM, VALUE [, STAT=]) | |
| 648 ``` | |
| 649 | |
| 650 ### Collective intrinsic subroutines | |
| 651 ``` | |
| 652 CALL CO_BROADCAST | |
| 653 CALL CO_MAX | |
| 654 CALL CO_MIN | |
| 655 CALL CO_REDUCE | |
| 656 CALL CO_SUM | |
| 657 ``` | |
| 658 | |
| 659 ## Non-standard intrinsics | |
| 660 ### PGI | |
| 661 ``` | |
| 662 AND, OR, XOR | |
| 663 LSHIFT, RSHIFT, SHIFT | |
| 664 ZEXT, IZEXT | |
| 665 COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D | |
| 666 COMPL | |
| 667 DCMPLX | |
| 668 EQV, NEQV | |
| 669 INT8 | |
| 670 JINT, JNINT, KNINT | |
| 671 LOC | |
| 672 ``` | |
| 673 | |
| 674 ### Intel | |
| 675 ``` | |
| 676 DCMPLX(X,Y), QCMPLX(X,Y) | |
| 677 DREAL(DOUBLE COMPLEX A) -> DOUBLE PRECISION | |
| 678 DFLOAT, DREAL | |
| 679 QEXT, QFLOAT, QREAL | |
| 680 DNUM, INUM, JNUM, KNUM, QNUM, RNUM - scan value from string | |
| 681 ZEXT | |
| 682 RAN, RANF | |
| 683 ILEN(I) = BIT_SIZE(I) | |
| 684 SIZEOF | |
| 685 MCLOCK, SECNDS | |
| 686 COTAN(X) = 1.0/TAN(X) | |
| 687 COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COTAND - degrees | |
| 688 AND, OR, XOR | |
| 689 LSHIFT, RSHIFT | |
| 690 IBCHNG, ISHA, ISHC, ISHL, IXOR | |
| 691 IARG, IARGC, NARGS, NUMARG | |
| 692 BADDRESS, IADDR | |
| 693 CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, LOC | |
| 694 MALLOC | |
| 695 ``` | |
| 696 | |
| 697 ## Intrinsic Procedure Name Resolution | |
| 698 | |
| 699 When the name of a procedure in a program is the same as the one of an intrinsic | |
| 700 procedure, and nothing other than its usage allows to decide whether the procedure | |
| 701 is the intrinsic or not (i.e, it does not appear in an INTRINSIC or EXTERNAL attribute | |
| 702 statement, is not an use/host associated procedure...), Fortran 2018 standard | |
| 703 section 19.5.1.4 point 6 rules that the procedure is established to be intrinsic if it is | |
| 704 invoked as an intrinsic procedure. | |
| 705 | |
| 706 In case the invocation would be an error if the procedure were the intrinsic | |
| 707 (e.g. wrong argument number or type), the broad wording of the standard | |
| 708 leaves two choices to the compiler: emit an error about the intrinsic invocation, | |
| 709 or consider this is an external procedure and emit no error. | |
| 710 | |
| 711 f18 will always consider this case to be the intrinsic and emit errors, unless the procedure | |
| 712 is used as a function (resp. subroutine) and the intrinsic is a subroutine (resp. function). | |
| 713 The table below gives some examples of decisions made by Fortran compilers in such case. | |
| 714 | |
| 715 | What is ACOS ? | Bad intrinsic call | External with warning | External no warning | Other error | | |
| 716 | --- | --- | --- | --- | --- | | |
| 717 | `print*, ACOS()` | gfortran, nag, xlf, f18 | ifort | nvfortran | | | |
| 718 | `print*, ACOS(I)` | gfortran, nag, xlf, f18 | ifort | nvfortran | | | |
| 719 | `print*, ACOS(X=I)` | gfortran, nag, xlf, f18 | ifort | | nvfortran (keyword on implicit extrenal )| | |
| 720 | `print*, ACOS(X, X)` | gfortran, nag, xlf, f18 | ifort | nvfortran | | | |
| 721 | `CALL ACOS(X)` | | | gfortran, nag, xlf, nvfortran, ifort, f18 | | | |
| 722 | |
| 723 | |
| 724 The rationale for f18 behavior is that when referring to a procedure with an | |
| 725 argument number or type that does not match the intrinsic specification, it seems safer to block | |
| 726 the rather likely case where the user is using the intrinsic the wrong way. | |
| 727 In case the user wanted to refer to an external function, he can add an explicit EXTERNAL | |
| 728 statement with no other consequences on the program. | |
| 729 However, it seems rather unlikely that a user would confuse an intrinsic subroutine for a | |
| 730 function and vice versa. Given no compiler is issuing an error here, changing the behavior might | |
| 731 affect existing programs that omit the EXTERNAL attribute in such case. | |
| 732 | |
| 733 Also note that in general, the standard gives the compiler the right to consider | |
| 734 any procedure that is not explicitly external as a non standard intrinsic (section 4.2 point 4). | |
| 735 So it is highly advised for the programmer to use EXTERNAL statements to prevent any ambiguity. | |
| 736 | |
| 737 ## Intrinsic Procedure Support in f18 | |
| 738 This section gives an overview of the support inside f18 libraries for the | |
| 739 intrinsic procedures listed above. | |
| 740 It may be outdated, refer to f18 code base for the actual support status. | |
| 741 | |
| 742 ### Semantic Analysis | |
| 743 F18 semantic expression analysis phase detects intrinsic procedure references, | |
| 744 validates the argument types and deduces the return types. | |
| 745 This phase currently supports all the intrinsic procedures listed above but the ones in the table below. | |
| 746 | |
| 747 | Intrinsic Category | Intrinsic Procedures Lacking Support | | |
| 748 | --- | --- | | |
| 749 | Coarray intrinsic functions | LCOBOUND, UCOBOUND, FAILED_IMAGES, GET_TEAM, IMAGE_INDEX, STOPPED_IMAGES, TEAM_NUMBER, THIS_IMAGE, COSHAPE | | |
| 750 | Object characteristic inquiry functions | ALLOCATED, ASSOCIATED, EXTENDS_TYPE_OF, IS_CONTIGUOUS, PRESENT, RANK, SAME_TYPE, STORAGE_SIZE | | |
| 751 | Type inquiry intrinsic functions | BIT_SIZE, DIGITS, EPSILON, HUGE, KIND, MAXEXPONENT, MINEXPONENT, NEW_LINE, PRECISION, RADIX, RANGE, TINY| | |
| 752 | Non-standard intrinsic functions | AND, OR, XOR, LSHIFT, RSHIFT, SHIFT, ZEXT, IZEXT, COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COMPL, DCMPLX, EQV, NEQV, INT8, JINT, JNINT, KNINT, LOC, QCMPLX, DREAL, DFLOAT, QEXT, QFLOAT, QREAL, DNUM, NUM, JNUM, KNUM, QNUM, RNUM, RAN, RANF, ILEN, SIZEOF, MCLOCK, SECNDS, COTAN, IBCHNG, ISHA, ISHC, ISHL, IXOR, IARG, IARGC, NARGS, NUMARG, BADDRESS, IADDR, CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, MALLOC | | |
| 753 | Intrinsic subroutines |MVBITS (elemental), CPU_TIME, DATE_AND_TIME, EVENT_QUERY, EXECUTE_COMMAND_LINE, GET_COMMAND, GET_COMMAND_ARGUMENT, GET_ENVIRONMENT_VARIABLE, MOVE_ALLOC, RANDOM_INIT, RANDOM_NUMBER, RANDOM_SEED, SYSTEM_CLOCK | | |
| 754 | Atomic intrinsic subroutines | ATOMIC_ADD &al. | | |
| 755 | Collective intrinsic subroutines | CO_BROADCAST &al. | | |
| 756 | |
| 757 | |
| 758 ### Intrinsic Function Folding | |
| 759 Fortran Constant Expressions can contain references to a certain number of | |
| 760 intrinsic functions (see Fortran 2018 standard section 10.1.12 for more details). | |
| 761 Constant Expressions may be used to define kind arguments. Therefore, the semantic | |
| 762 expression analysis phase must be able to fold references to intrinsic functions | |
| 763 listed in section 10.1.12. | |
| 764 | |
| 765 F18 intrinsic function folding is either performed by implementations directly | |
| 766 operating on f18 scalar types or by using host runtime functions and | |
| 767 host hardware types. F18 supports folding elemental intrinsic functions over | |
| 768 arrays when an implementation is provided for the scalars (regardless of whether | |
| 769 it is using host hardware types or not). | |
| 770 The status of intrinsic function folding support is given in the sub-sections below. | |
| 771 | |
| 772 #### Intrinsic Functions with Host Independent Folding Support | |
| 773 Implementations using f18 scalar types enables folding intrinsic functions | |
| 774 on any host and with any possible type kind supported by f18. The intrinsic functions | |
| 775 listed below are folded using host independent implementations. | |
| 776 | |
| 777 | Return Type | Intrinsic Functions with Host Independent Folding Support| | |
| 778 | --- | --- | | |
| 779 | INTEGER| ABS(INTEGER(k)), DIM(INTEGER(k), INTEGER(k)), DSHIFTL, DSHIFTR, IAND, IBCLR, IBSET, IEOR, INT, IOR, ISHFT, KIND, LEN, LEADZ, MASKL, MASKR, MERGE_BITS, POPCNT, POPPAR, SHIFTA, SHIFTL, SHIFTR, TRAILZ | | |
| 780 | REAL | ABS(REAL(k)), ABS(COMPLEX(k)), AIMAG, AINT, DPROD, REAL | | |
| 781 | COMPLEX | CMPLX, CONJG | | |
| 782 | LOGICAL | BGE, BGT, BLE, BLT | | |
| 783 | |
| 784 #### Intrinsic Functions with Host Dependent Folding Support | |
| 785 Implementations using the host runtime may not be available for all supported | |
| 786 f18 types depending on the host hardware types and the libraries available on the host. | |
| 787 The actual support on a host depends on what the host hardware types are. | |
| 788 The list below gives the functions that are folded using host runtime and the related C/C++ types. | |
| 789 F18 automatically detects if these types match an f18 scalar type. If so, | |
| 790 folding of the intrinsic functions will be possible for the related f18 scalar type, | |
| 791 otherwise an error message will be produced by f18 when attempting to fold related intrinsic functions. | |
| 792 | |
| 793 | C/C++ Host Type | Intrinsic Functions with Host Standard C++ Library Based Folding Support | | |
| 794 | --- | --- | | |
| 795 | float, double and long double | ACOS, ACOSH, ASINH, ATAN, ATAN2, ATANH, COS, COSH, ERF, ERFC, EXP, GAMMA, HYPOT, LOG, LOG10, LOG_GAMMA, MOD, SIN, SQRT, SINH, SQRT, TAN, TANH | | |
| 796 | std::complex for float, double and long double| ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH, COS, COSH, EXP, LOG, SIN, SINH, SQRT, TAN, TANH | | |
| 797 | |
| 798 On top of the default usage of C++ standard library functions for folding described | |
| 799 in the table above, it is possible to compile f18 evaluate library with | |
| 800 [libpgmath](https://github.com/flang-compiler/flang/tree/master/runtime/libpgmath) | |
| 801 so that it can be used for folding. To do so, one must have a compiled version | |
| 802 of the libpgmath library available on the host and add | |
| 803 `-DLIBPGMATH_DIR=<path to the compiled shared libpgmath library>` to the f18 cmake command. | |
| 804 | |
| 805 Libpgmath comes with real and complex functions that replace C++ standard library | |
| 806 float and double functions to fold all the intrinsic functions listed in the table above. | |
| 807 It has no long double versions. If the host long double matches an f18 scalar type, | |
| 808 C++ standard library functions will still be used for folding expressions with this scalar type. | |
| 809 Libpgmath adds the possibility to fold the following functions for f18 real scalar | |
| 810 types related to host float and double types. | |
| 811 | |
| 812 | C/C++ Host Type | Additional Intrinsic Function Folding Support with Libpgmath (Optional) | | |
| 813 | --- | --- | | |
| 814 |float and double| BESSEL_J0, BESSEL_J1, BESSEL_JN (elemental only), BESSEL_Y0, BESSEL_Y1, BESSEL_Yn (elemental only), ERFC_SCALED | | |
| 815 | |
| 816 Libpgmath comes in three variants (precise, relaxed and fast). So far, only the | |
| 817 precise version is used for intrinsic function folding in f18. It guarantees the greatest numerical precision. | |
| 818 | |
| 819 ### Intrinsic Functions with Missing Folding Support | |
| 820 The following intrinsic functions are allowed in constant expressions but f18 | |
| 821 is not yet able to fold them. Note that there might be constraints on the arguments | |
| 822 so that these intrinsics can be used in constant expressions (see section 10.1.12 of Fortran 2018 standard). | |
| 823 | |
| 824 ALL, ACHAR, ADJUSTL, ADJUSTR, ANINT, ANY, BESSEL_JN (transformational only), | |
| 825 BESSEL_YN (transformational only), BTEST, CEILING, CHAR, COUNT, CSHIFT, DOT_PRODUCT, | |
| 826 DIM (REAL only), DOT_PRODUCT, EOSHIFT, FINDLOC, FLOOR, FRACTION, HUGE, IACHAR, IALL, | |
| 827 IANY, IPARITY, IBITS, ICHAR, IMAGE_STATUS, INDEX, ISHFTC, IS_IOSTAT_END, | |
| 828 IS_IOSTAT_EOR, LBOUND, LEN_TRIM, LGE, LGT, LLE, LLT, LOGICAL, MATMUL, MAX, MAXLOC, | |
| 829 MAXVAL, MERGE, MIN, MINLOC, MINVAL, MOD (INTEGER only), MODULO, NEAREST, NINT, | |
| 830 NORM2, NOT, OUT_OF_RANGE, PACK, PARITY, PRODUCT, REPEAT, REDUCE, RESHAPE, | |
| 831 RRSPACING, SCAN, SCALE, SELECTED_CHAR_KIND, SELECTED_INT_KIND, SELECTED_REAL_KIND, | |
| 832 SET_EXPONENT, SHAPE, SIGN, SIZE, SPACING, SPREAD, SUM, TINY, TRANSFER, TRANSPOSE, | |
| 833 TRIM, UBOUND, UNPACK, VERIFY. | |
| 834 | |
| 835 Coarray, non standard, IEEE and ISO_C_BINDINGS intrinsic functions that can be | |
| 836 used in constant expressions have currently no folding support at all. |