blob: ccb93e104dab6594fda4ef90cd769d8421b79462 [file] [log] [blame] [view]
Sourabh Singh Tomar932aae72020-09-10 17:34:371<!--===- 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
peter klauslere7c5a4702018-09-25 22:23:019# A categorization of standard (2018) and extended Fortran intrinsic procedures
10
cor3ntinb7ff0322023-09-25 12:02:3911```{contents}
12---
13local:
14---
Richard Barton271a7bb2020-09-11 13:17:1915```
16
peter klauslere7c5a4702018-09-25 22:23:0117This note attempts to group the intrinsic procedures of Fortran into categories
18of functions or subroutines with similar interfaces as an aid to
19comprehension beyond that which might be gained from the standard's
20alphabetical list.
21
Jean Perier3774e9d2019-03-29 15:48:3922A brief status of intrinsic procedure support in f18 is also given at the end.
23
peter klauslere7c5a4702018-09-25 22:23:0124Few procedures are actually described here apart from their interfaces; see the
25Fortran 2018 standard (section 16) for the complete story.
26
27Intrinsic modules are not covered here.
peter klausler3cecff62018-09-25 20:26:3528
29## General rules
30
peter klauslere7c5a4702018-09-25 22:23:01311. The value of any intrinsic function's `KIND` actual argument, if present,
32 must be a scalar constant integer expression, of any kind, whose value
peter klausler3cecff62018-09-25 20:26:3533 resolves to some supported kind of the function's result type.
34 If optional and absent, the kind of the function's result is
35 either the default kind of that category or to the kind of an argument
36 (e.g., as in `AINT`).
371. Procedures are summarized with a non-Fortran syntax for brevity.
38 Wherever a function has a short definition, it appears after an
peter klauslere7c5a4702018-09-25 22:23:0139 equal sign as if it were a statement function. Any functions referenced
40 in these short summaries are intrinsic.
peter klausler3cecff62018-09-25 20:26:35411. Unless stated otherwise, an actual argument may have any supported kind
42 of a particular intrinsic type. Sometimes a pattern variable
43 can appear in a description (e.g., `REAL(k)`) when the kind of an
44 actual argument's type must match the kind of another argument, or
45 determines the kind type parameter of the function result.
461. When an intrinsic type name appears without a kind (e.g., `REAL`),
47 it refers to the default kind of that type. Sometimes the word
48 `default` will appear for clarity.
peter klauslere7c5a4702018-09-25 22:23:01491. The names of the dummy arguments actually matter because they can
50 be used as keywords for actual arguments.
511. All standard intrinsic functions are pure, even when not elemental.
peter klausler9849cf52018-09-25 21:47:55521. Assumed-rank arguments may not appear as actual arguments unless
53 expressly permitted.
peter klauslerbab1f672018-09-26 17:42:55541. When an argument is described with a default value, e.g. `KIND=KIND(0)`,
55 it is an optional argument. Optional arguments without defaults,
56 e.g. `DIM` on many transformationals, are wrapped in `[]` brackets
57 as in the Fortran standard. When an intrinsic has optional arguments
58 with and without default values, the arguments with default values
59 may appear within the brackets to preserve the order of arguments
60 (e.g., `COUNT`).
peter klausler3cecff62018-09-25 20:26:3561
Richard Barton271a7bb2020-09-11 13:17:1962## Elemental intrinsic functions
peter klausler3cecff62018-09-25 20:26:3563
peter klauslere7c5a4702018-09-25 22:23:0164Pure elemental semantics apply to these functions, to wit: when one or more of
peter klausler3cecff62018-09-25 20:26:3565the actual arguments are arrays, the arguments must be conformable, and
66the result is also an array.
67Scalar arguments are expanded when the arguments are not all scalars.
68
Richard Barton271a7bb2020-09-11 13:17:1969### Elemental intrinsic functions that may have unrestricted specific procedures
peter klausler370c44a2018-09-25 23:59:4170
peter klauslere7c5a4702018-09-25 22:23:0171When an elemental intrinsic function is documented here as having an
peter klausler9849cf52018-09-25 21:47:5572_unrestricted specific name_, that name may be passed as an actual
peter klauslere7c5a4702018-09-25 22:23:0173argument, used as the target of a procedure pointer, appear in
74a generic interface, and be otherwise used as if it were an external
75procedure.
peter klauslere7c5a4702018-09-25 22:23:0176An `INTRINSIC` statement or attribute may have to be applied to an
peter klausler370c44a2018-09-25 23:59:4177unrestricted specific name to enable such usage.
peter klauslere7c5a4702018-09-25 22:23:0178
peter klausler42d17f22018-09-26 19:58:4379When a name is being used as a specific procedure for any purpose other
80than that of a called function, the specific instance of the function
81that accepts and returns values of the default kinds of the intrinsic
82types is used.
peter klauslere7c5a4702018-09-25 22:23:0183A Fortran `INTERFACE` could be written to define each of
84these unrestricted specific intrinsic function names.
85
peter klausler3cecff62018-09-25 20:26:3586Calls to dummy arguments and procedure pointers that correspond to these
87specific names must pass only scalar actual argument values.
88
89No other intrinsic function name can be passed as an actual argument,
peter klausler42d17f22018-09-26 19:58:4390used as a pointer target, appear in a generic interface, or be otherwise
91used except as the name of a called function.
92Some of these _restricted specific intrinsic functions_, e.g. `FLOAT`,
93provide a means for invoking a corresponding generic (`REAL` in the case of `FLOAT`)
94with forced argument and result kinds.
95Others, viz. `CHAR`, `ICHAR`, `INT`, `REAL`, and the lexical comparisons like `LGE`,
96have the same name as their generic functions, and it is not clear what purpose
97is accomplished by the standard by defining them as specific functions.
peter klausler9849cf52018-09-25 21:47:5598
99### Trigonometric elemental intrinsic functions, generic and (mostly) specific
100All of these functions can be used as unrestricted specific names.
101
102```
103ACOS(REAL(k) X) -> REAL(k)
104ASIN(REAL(k) X) -> REAL(k)
105ATAN(REAL(k) X) -> REAL(k)
106ATAN(REAL(k) Y, REAL(k) X) -> REAL(k) = ATAN2(Y, X)
107ATAN2(REAL(k) Y, REAL(k) X) -> REAL(k)
108COS(REAL(k) X) -> REAL(k)
109COSH(REAL(k) X) -> REAL(k)
110SIN(REAL(k) X) -> REAL(k)
111SINH(REAL(k) X) -> REAL(k)
112TAN(REAL(k) X) -> REAL(k)
113TANH(REAL(k) X) -> REAL(k)
114```
115
116These `COMPLEX` versions of some of those functions, and the
117inverse hyperbolic functions, cannot be used as specific names.
118```
119ACOS(COMPLEX(k) X) -> COMPLEX(k)
120ASIN(COMPLEX(k) X) -> COMPLEX(k)
121ATAN(COMPLEX(k) X) -> COMPLEX(k)
122ACOSH(REAL(k) X) -> REAL(k)
123ACOSH(COMPLEX(k) X) -> COMPLEX(k)
124ASINH(REAL(k) X) -> REAL(k)
125ASINH(COMPLEX(k) X) -> COMPLEX(k)
126ATANH(REAL(k) X) -> REAL(k)
127ATANH(COMPLEX(k) X) -> COMPLEX(k)
128COS(COMPLEX(k) X) -> COMPLEX(k)
129COSH(COMPLEX(k) X) -> COMPLEX(k)
130SIN(COMPLEX(k) X) -> COMPLEX(k)
131SINH(COMPLEX(k) X) -> COMPLEX(k)
132TAN(COMPLEX(k) X) -> COMPLEX(k)
133TANH(COMPLEX(k) X) -> COMPLEX(k)
134```
135
136### Non-trigonometric elemental intrinsic functions, generic and specific
peter klauslere7c5a4702018-09-25 22:23:01137These functions *can* be used as unrestricted specific names.
peter klausler9849cf52018-09-25 21:47:55138```
peter klauslere7c5a4702018-09-25 22:23:01139ABS(REAL(k) A) -> REAL(k) = SIGN(A, 0.0)
140AIMAG(COMPLEX(k) Z) -> REAL(k) = Z%IM
peter klauslerbab1f672018-09-26 17:42:55141AINT(REAL(k) A, KIND=k) -> REAL(KIND)
142ANINT(REAL(k) A, KIND=k) -> REAL(KIND)
peter klauslere7c5a4702018-09-25 22:23:01143CONJG(COMPLEX(k) Z) -> COMPLEX(k) = CMPLX(Z%RE, -Z%IM)
peter klausler370c44a2018-09-25 23:59:41144DIM(REAL(k) X, REAL(k) Y) -> REAL(k) = X-MIN(X,Y)
peter klausler9849cf52018-09-25 21:47:55145DPROD(default REAL X, default REAL Y) -> DOUBLE PRECISION = DBLE(X)*DBLE(Y)
146EXP(REAL(k) X) -> REAL(k)
peter klauslerbab1f672018-09-26 17:42:55147INDEX(CHARACTER(k) STRING, CHARACTER(k) SUBSTRING, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
148LEN(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n
peter klausler9849cf52018-09-25 21:47:55149LOG(REAL(k) X) -> REAL(k)
150LOG10(REAL(k) X) -> REAL(k)
151MOD(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k) = A-P*INT(A/P)
peter klauslerbab1f672018-09-26 17:42:55152NINT(REAL(k) A, KIND=KIND(0)) -> INTEGER(KIND)
peter klausler9849cf52018-09-25 21:47:55153SIGN(REAL(k) A, REAL(k) B) -> REAL(k)
peter klauslere7c5a4702018-09-25 22:23:01154SQRT(REAL(k) X) -> REAL(k) = X ** 0.5
peter klausler9849cf52018-09-25 21:47:55155```
156
peter klausler970e746c2018-09-25 22:36:00157These variants, however *cannot* be used as specific names without recourse to an alias
158from the following section:
peter klausler9849cf52018-09-25 21:47:55159```
peter klauslere7c5a4702018-09-25 22:23:01160ABS(INTEGER(k) A) -> INTEGER(k) = SIGN(A, 0)
161ABS(COMPLEX(k) A) -> REAL(k) = HYPOT(A%RE, A%IM)
peter klausler370c44a2018-09-25 23:59:41162DIM(INTEGER(k) X, INTEGER(k) Y) -> INTEGER(k) = X-MIN(X,Y)
peter klausler9849cf52018-09-25 21:47:55163EXP(COMPLEX(k) X) -> COMPLEX(k)
164LOG(COMPLEX(k) X) -> COMPLEX(k)
peter klauslere7c5a4702018-09-25 22:23:01165MOD(REAL(k) A, REAL(k) P) -> REAL(k) = A-P*INT(A/P)
peter klausler9849cf52018-09-25 21:47:55166SIGN(INTEGER(k) A, INTEGER(k) B) -> INTEGER(k)
peter klausler370c44a2018-09-25 23:59:41167SQRT(COMPLEX(k) X) -> COMPLEX(k)
peter klausler9849cf52018-09-25 21:47:55168```
peter klausler3cecff62018-09-25 20:26:35169
170### Unrestricted specific aliases for some elemental intrinsic functions with distinct names
171
172```
peter klausler9849cf52018-09-25 21:47:55173ALOG(REAL X) -> REAL = LOG(X)
174ALOG10(REAL X) -> REAL = LOG10(X)
175AMOD(REAL A, REAL P) -> REAL = MOD(A, P)
176CABS(COMPLEX A) = ABS(A)
177CCOS(COMPLEX X) = COS(X)
178CEXP(COMPLEX A) -> COMPLEX = EXP(A)
179CLOG(COMPLEX X) -> COMPLEX = LOG(X)
peter klausler42b33da2018-09-29 00:02:11180CSIN(COMPLEX X) -> COMPLEX = SIN(X)
peter klausler9849cf52018-09-25 21:47:55181CSQRT(COMPLEX X) -> COMPLEX = SQRT(X)
peter klausler42b33da2018-09-29 00:02:11182CTAN(COMPLEX X) -> COMPLEX = TAN(X)
183DABS(DOUBLE PRECISION A) -> DOUBLE PRECISION = ABS(A)
184DACOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = ACOS(X)
185DASIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ASIN(X)
186DATAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN(X)
187DATAN2(DOUBLE PRECISION Y, DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN2(Y, X)
188DCOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = COS(X)
189DCOSH(DOUBLE PRECISION X) -> DOUBLE PRECISION = COSH(X)
peter klausler370c44a2018-09-25 23:59:41190DDIM(DOUBLE PRECISION X, DOUBLE PRECISION Y) -> DOUBLE PRECISION = X-MIN(X,Y)
peter klausler42b33da2018-09-29 00:02:11191DEXP(DOUBLE PRECISION X) -> DOUBLE PRECISION = EXP(X)
peter klausler9849cf52018-09-25 21:47:55192DINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = AINT(A)
193DLOG(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG(X)
194DLOG10(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG10(X)
195DMOD(DOUBLE PRECISION A, DOUBLE PRECISION P) -> DOUBLE PRECISION = MOD(A, P)
peter klausler42b33da2018-09-29 00:02:11196DNINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = ANINT(A)
peter klausler9849cf52018-09-25 21:47:55197DSIGN(DOUBLE PRECISION A, DOUBLE PRECISION B) -> DOUBLE PRECISION = SIGN(A, B)
peter klausler42b33da2018-09-29 00:02:11198DSIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = SIN(X)
199DSINH(DOUBLE PRECISION X) -> DOUBLE PRECISION = SINH(X)
peter klausler9849cf52018-09-25 21:47:55200DSQRT(DOUBLE PRECISION X) -> DOUBLE PRECISION = SQRT(X)
peter klausler42b33da2018-09-29 00:02:11201DTAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = TAN(X)
202DTANH(DOUBLE PRECISION X) -> DOUBLE PRECISION = TANH(X)
203IABS(INTEGER A) -> INTEGER = ABS(A)
peter klausler370c44a2018-09-25 23:59:41204IDIM(INTEGER X, INTEGER Y) -> INTEGER = X-MIN(X,Y)
peter klausler42b33da2018-09-29 00:02:11205IDNINT(DOUBLE PRECISION A) -> INTEGER = NINT(A)
peter klausler9849cf52018-09-25 21:47:55206ISIGN(INTEGER A, INTEGER B) -> INTEGER = SIGN(A, B)
peter klausler3cecff62018-09-25 20:26:35207```
208
209## Generic elemental intrinsic functions without specific names
210
peter klausler9849cf52018-09-25 21:47:55211(No procedures after this point can be passed as actual arguments, used as
212pointer targets, or appear as specific procedures in generic interfaces.)
213
peter klausler3cecff62018-09-25 20:26:35214### Elemental conversions
215
216```
peter klauslerbab1f672018-09-26 17:42:55217ACHAR(INTEGER(k) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1)
218CEILING(REAL() A, KIND=KIND(0)) -> INTEGER(KIND)
219CHAR(INTEGER(any) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1)
220CMPLX(COMPLEX(k) X, KIND=KIND(0.0D0)) -> COMPLEX(KIND)
221CMPLX(INTEGER or REAL or BOZ X, INTEGER or REAL or BOZ Y=0, KIND=KIND((0,0))) -> COMPLEX(KIND)
peter klausleref9dd9d2018-10-17 22:09:48222DBLE(INTEGER or REAL or COMPLEX or BOZ A) = REAL(A, KIND=KIND(0.0D0))
peter klausler9849cf52018-09-25 21:47:55223EXPONENT(REAL(any) X) -> default INTEGER
peter klauslerbab1f672018-09-26 17:42:55224FLOOR(REAL(any) A, KIND=KIND(0)) -> INTEGER(KIND)
225IACHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND)
226ICHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND)
227INT(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0)) -> INTEGER(KIND)
228LOGICAL(LOGICAL(any) L, KIND=KIND(.TRUE.)) -> LOGICAL(KIND)
229REAL(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0.0)) -> REAL(KIND)
peter klausler3cecff62018-09-25 20:26:35230```
231
232### Other generic elemental intrinsic functions without specific names
233N.B. `BESSEL_JN(N1, N2, X)` and `BESSEL_YN(N1, N2, X)` are categorized
peter klausler9849cf52018-09-25 21:47:55234below with the _transformational_ intrinsic functions.
peter klausler3cecff62018-09-25 20:26:35235
236```
peter klausler9849cf52018-09-25 21:47:55237BESSEL_J0(REAL(k) X) -> REAL(k)
238BESSEL_J1(REAL(k) X) -> REAL(k)
239BESSEL_JN(INTEGER(n) N, REAL(k) X) -> REAL(k)
240BESSEL_Y0(REAL(k) X) -> REAL(k)
241BESSEL_Y1(REAL(k) X) -> REAL(k)
242BESSEL_YN(INTEGER(n) N, REAL(k) X) -> REAL(k)
243ERF(REAL(k) X) -> REAL(k)
244ERFC(REAL(k) X) -> REAL(k)
245ERFC_SCALED(REAL(k) X) -> REAL(k)
246FRACTION(REAL(k) X) -> REAL(k)
247GAMMA(REAL(k) X) -> REAL(k)
peter klausler970e746c2018-09-25 22:36:00248HYPOT(REAL(k) X, REAL(k) Y) -> REAL(k) = SQRT(X*X+Y*Y) without spurious overflow
peter klausler42b33da2018-09-29 00:02:11249IMAGE_STATUS(INTEGER(any) IMAGE [, scalar TEAM_TYPE TEAM ]) -> default INTEGER
peter klausler9849cf52018-09-25 21:47:55250IS_IOSTAT_END(INTEGER(any) I) -> default LOGICAL
251IS_IOSTAT_EOR(INTEGER(any) I) -> default LOGICAL
252LOG_GAMMA(REAL(k) X) -> REAL(k)
253MAX(INTEGER(k) ...) -> INTEGER(k)
254MAX(REAL(k) ...) -> REAL(k)
255MAX(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...)))
256MERGE(any type TSOURCE, same type FSOURCE, LOGICAL(any) MASK) -> type of FSOURCE
257MIN(INTEGER(k) ...) -> INTEGER(k)
258MIN(REAL(k) ...) -> REAL(k)
259MIN(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...)))
260MODULO(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k); P*result >= 0
261MODULO(REAL(k) A, REAL(k) P) -> REAL(k) = A - P*FLOOR(A/P)
262NEAREST(REAL(k) X, REAL(any) S) -> REAL(k)
peter klauslerbab1f672018-09-26 17:42:55263OUT_OF_RANGE(INTEGER(any) X, scalar INTEGER or REAL(k) MOLD) -> default LOGICAL
264OUT_OF_RANGE(REAL(any) X, scalar REAL(k) MOLD) -> default LOGICAL
265OUT_OF_RANGE(REAL(any) X, scalar INTEGER(any) MOLD, scalar LOGICAL(any) ROUND=.FALSE.) -> default LOGICAL
peter klausler9849cf52018-09-25 21:47:55266RRSPACING(REAL(k) X) -> REAL(k)
267SCALE(REAL(k) X, INTEGER(any) I) -> REAL(k)
268SET_EXPONENT(REAL(k) X, INTEGER(any) I) -> REAL(k)
269SPACING(REAL(k) X) -> REAL(k)
peter klausler3cecff62018-09-25 20:26:35270```
271
peter klausler9849cf52018-09-25 21:47:55272### Restricted specific aliases for elemental conversions &/or extrema with default intrinsic types
peter klausler3cecff62018-09-25 20:26:35273
274```
peter klausler9849cf52018-09-25 21:47:55275AMAX0(INTEGER ...) = REAL(MAX(...))
276AMAX1(REAL ...) = MAX(...)
277AMIN0(INTEGER...) = REAL(MIN(...))
278AMIN1(REAL ...) = MIN(...)
peter klausler9849cf52018-09-25 21:47:55279DMAX1(DOUBLE PRECISION ...) = MAX(...)
280DMIN1(DOUBLE PRECISION ...) = MIN(...)
281FLOAT(INTEGER I) = REAL(I)
282IDINT(DOUBLE PRECISION A) = INT(A)
283IFIX(REAL A) = INT(A)
284MAX0(INTEGER ...) = MAX(...)
285MAX1(REAL ...) = INT(MAX(...))
286MIN0(INTEGER ...) = MIN(...)
287MIN1(REAL ...) = INT(MIN(...))
288SNGL(DOUBLE PRECISION A) = REAL(A)
peter klausler3cecff62018-09-25 20:26:35289```
290
291### Generic elemental bit manipulation intrinsic functions
peter klauslerbab1f672018-09-26 17:42:55292Many of these accept a typeless "BOZ" literal as an actual argument.
293It is interpreted as having the kind of intrinsic `INTEGER` type
294as another argument, as if the typeless were implicitly wrapped
295in a call to `INT()`.
296When multiple arguments can be either `INTEGER` values or typeless
297constants, it is forbidden for *all* of them to be typeless
298constants if the result of the function is `INTEGER`
299(i.e., only `BGE`, `BGT`, `BLE`, and `BLT` can have multiple
300typeless arguments).
301
peter klausler3cecff62018-09-25 20:26:35302```
peter klauslere7c5a4702018-09-25 22:23:01303BGE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
304BGT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
305BLE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
306BLT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
peter klausler9849cf52018-09-25 21:47:55307BTEST(INTEGER(n1) I, INTEGER(n2) POS) -> default LOGICAL
peter klausler42b33da2018-09-29 00:02:11308DSHIFTL(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k)
peter klausler9849cf52018-09-25 21:47:55309DSHIFTL(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k)
peter klausler42b33da2018-09-29 00:02:11310DSHIFTR(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k)
peter klausler9849cf52018-09-25 21:47:55311DSHIFTR(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k)
312IAND(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
313IAND(BOZ I, INTEGER(k) J) -> INTEGER(k)
314IBCLR(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k)
peter klausler9849cf52018-09-25 21:47:55315IBITS(INTEGER(k) I, INTEGER(n1) POS, INTEGER(n2) LEN) -> INTEGER(k)
peter klausler42b33da2018-09-29 00:02:11316IBSET(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k)
peter klausler9849cf52018-09-25 21:47:55317IEOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
318IEOR(BOZ I, INTEGER(k) J) -> INTEGER(k)
319IOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
320IOR(BOZ I, INTEGER(k) J) -> INTEGER(k)
321ISHFT(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
peter klauslerbab1f672018-09-26 17:42:55322ISHFTC(INTEGER(k) I, INTEGER(n1) SHIFT, INTEGER(n2) SIZE=BIT_SIZE(I)) -> INTEGER(k)
peter klausler9849cf52018-09-25 21:47:55323LEADZ(INTEGER(any) I) -> default INTEGER
peter klauslerbab1f672018-09-26 17:42:55324MASKL(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND)
325MASKR(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND)
peter klausler9849cf52018-09-25 21:47:55326MERGE_BITS(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK)))
327MERGE_BITS(BOZ I, INTEGER(k) J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK)))
328NOT(INTEGER(k) I) -> INTEGER(k)
329POPCNT(INTEGER(any) I) -> default INTEGER
peter klauslere7c5a4702018-09-25 22:23:01330POPPAR(INTEGER(any) I) -> default INTEGER = IAND(POPCNT(I), Z'1')
peter klausler9849cf52018-09-25 21:47:55331SHIFTA(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
332SHIFTL(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
333SHIFTR(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
334TRAILZ(INTEGER(any) I) -> default INTEGER
peter klausler3cecff62018-09-25 20:26:35335```
336
337### Character elemental intrinsic functions
338See also `INDEX` and `LEN` above among the elemental intrinsic functions with
339unrestricted specific names.
peter klausler9849cf52018-09-25 21:47:55340```
341ADJUSTL(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n)
342ADJUSTR(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n)
peter klauslerbab1f672018-09-26 17:42:55343LEN_TRIM(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n
peter klausler9849cf52018-09-25 21:47:55344LGE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
345LGT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
346LLE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
347LLT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
peter klauslerbab1f672018-09-26 17:42:55348SCAN(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
349VERIFY(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
peter klausler9849cf52018-09-25 21:47:55350```
peter klausler3cecff62018-09-25 20:26:35351
peter klausler9849cf52018-09-25 21:47:55352`SCAN` returns the index of the first (or last, if `BACK=.TRUE.`) character in `STRING`
353that is present in `SET`, or zero if none is.
354
peter klauslerbab1f672018-09-26 17:42:55355`VERIFY` is essentially the opposite: it returns the index of the first (or last) character
peter klausler9849cf52018-09-25 21:47:55356in `STRING` that is *not* present in `SET`, or zero if all are.
peter klausler3cecff62018-09-25 20:26:35357
Richard Barton271a7bb2020-09-11 13:17:19358## Transformational intrinsic functions
peter klausler3cecff62018-09-25 20:26:35359
peter klausler9849cf52018-09-25 21:47:55360This category comprises a large collection of intrinsic functions that
361are collected together because they somehow transform their arguments
362in a way that prevents them from being elemental.
peter klauslere7c5a4702018-09-25 22:23:01363All of them are pure, however.
peter klausler9849cf52018-09-25 21:47:55364
365Some general rules apply to the transformational intrinsic functions:
366
peter klausler3cecff62018-09-25 20:26:353671. `DIM` arguments are optional; if present, the actual argument must be
368 a scalar integer of any kind.
3691. When an optional `DIM` argument is absent, or an `ARRAY` or `MASK`
370 argument is a vector, the result of the function is scalar; otherwise,
371 the result is an array of the same shape as the `ARRAY` or `MASK`
372 argument with the dimension `DIM` removed from the shape.
3731. When a function takes an optional `MASK` argument, it must be conformable
374 with its `ARRAY` argument if it is present, and the mask can be any kind
375 of `LOGICAL`. It can be scalar.
3761. The type `numeric` here can be any kind of `INTEGER`, `REAL`, or `COMPLEX`.
3771. The type `relational` here can be any kind of `INTEGER`, `REAL`, or `CHARACTER`.
3781. The type `any` here denotes any intrinsic or derived type.
peter klausler9849cf52018-09-25 21:47:553791. The notation `(..)` denotes an array of any rank (but not an assumed-rank array).
peter klausler3cecff62018-09-25 20:26:35380
Richard Barton271a7bb2020-09-11 13:17:19381### Logical reduction transformational intrinsic functions
peter klausler3cecff62018-09-25 20:26:35382```
peter klausler9849cf52018-09-25 21:47:55383ALL(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
384ANY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
385COUNT(LOGICAL(any) MASK(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
386PARITY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
peter klausler3cecff62018-09-25 20:26:35387```
388
Richard Barton271a7bb2020-09-11 13:17:19389### Numeric reduction transformational intrinsic functions
peter klausler3cecff62018-09-25 20:26:35390```
peter klausler9849cf52018-09-25 21:47:55391IALL(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
392IANY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
393IPARITY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
394NORM2(REAL(k) X(..) [, DIM ]) -> REAL(k)
395PRODUCT(numeric ARRAY(..) [, DIM, MASK ]) -> numeric
396SUM(numeric ARRAY(..) [, DIM, MASK ]) -> numeric
peter klausler3cecff62018-09-25 20:26:35397```
398
peter klausler970e746c2018-09-25 22:36:00399`NORM2` generalizes `HYPOT` by computing `SQRT(SUM(X*X))` while avoiding spurious overflows.
400
Richard Barton271a7bb2020-09-11 13:17:19401### Extrema reduction transformational intrinsic functions
peter klausler3cecff62018-09-25 20:26:35402```
peter klausler9849cf52018-09-25 21:47:55403MAXVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k)
404MINVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k)
peter klausler3cecff62018-09-25 20:26:35405```
406
407### Locational transformational intrinsic functions
408When the optional `DIM` argument is absent, the result is an `INTEGER(KIND)`
409vector whose length is the rank of `ARRAY`.
410When the optional `DIM` argument is present, the result is an `INTEGER(KIND)`
411array of rank `RANK(ARRAY)-1` and shape equal to that of `ARRAY` with
412the dimension `DIM` removed.
413
peter klausler9849cf52018-09-25 21:47:55414The optional `BACK` argument is a scalar LOGICAL value of any kind.
415When present and `.TRUE.`, it causes the function to return the index
416of the *last* occurence of the target or extreme value.
417
peter klausler3cecff62018-09-25 20:26:35418For `FINDLOC`, `ARRAY` may have any of the five intrinsic types, and `VALUE`
419must a scalar value of a type for which `ARRAY==VALUE` or `ARRAY .EQV. VALUE`
420is an acceptable expression.
421
422```
peter klauslerbab1f672018-09-26 17:42:55423FINDLOC(intrinsic ARRAY(..), scalar VALUE [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
424MAXLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
425MINLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
peter klausler3cecff62018-09-25 20:26:35426```
427
Richard Barton271a7bb2020-09-11 13:17:19428### Data rearrangement transformational intrinsic functions
peter klausler3cecff62018-09-25 20:26:35429The optional `DIM` argument to these functions must be a scalar integer of
430any kind, and it takes a default value of 1 when absent.
431
432```
peter klausler9849cf52018-09-25 21:47:55433CSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, DIM ]) -> same type/kind/shape as ARRAY
peter klausler3cecff62018-09-25 20:26:35434```
peter klausler9849cf52018-09-25 21:47:55435Either `SHIFT` is scalar or `RANK(SHIFT) == RANK(ARRAY) - 1` and `SHAPE(SHIFT)` is that of `SHAPE(ARRAY)` with element `DIM` removed.
peter klausler3cecff62018-09-25 20:26:35436
437```
peter klausler9849cf52018-09-25 21:47:55438EOSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, BOUNDARY, DIM ]) -> same type/kind/shape as ARRAY
peter klausler3cecff62018-09-25 20:26:35439```
440* `SHIFT` is scalar or `RANK(SHIFT) == RANK(ARRAY) - 1` and `SHAPE(SHIFT)` is that of `SHAPE(ARRAY)` with element `DIM` removed.
441* If `BOUNDARY` is present, it must have the same type and parameters as `ARRAY`.
442* 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)`.
443* 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`
444 removed.
445
446```
peter klausler9849cf52018-09-25 21:47:55447PACK(any ARRAY(..), LOGICAL(any) MASK(..)) -> vector of same type and kind as ARRAY
peter klausler3cecff62018-09-25 20:26:35448```
449* `MASK` is conformable with `ARRAY` and may be scalar.
450* The length of the result vector is `COUNT(MASK)` if `MASK` is an array, else `SIZE(ARRAY)` if `MASK` is `.TRUE.`, else zero.
451
452```
peter klausler9849cf52018-09-25 21:47:55453PACK(any ARRAY(..), LOGICAL(any) MASK(..), any VECTOR(n)) -> vector of same type, kind, and size as VECTOR
peter klausler3cecff62018-09-25 20:26:35454```
455* `MASK` is conformable with `ARRAY` and may be scalar.
456* `VECTOR` has the same type and kind as `ARRAY`.
457* `VECTOR` must not be smaller than result of `PACK` with no `VECTOR` argument.
458* The leading elements of `VECTOR` are replaced with elements from `ARRAY` as
459 if `PACK` had been invoked without `VECTOR`.
460
461```
peter klausler9849cf52018-09-25 21:47:55462RESHAPE(any SOURCE(..), INTEGER(k) SHAPE(n) [, PAD(..), INTEGER(k2) ORDER(n) ]) -> SOURCE array with shape SHAPE
peter klausler3cecff62018-09-25 20:26:35463```
464* If `ORDER` is present, it is a vector of the same size as `SHAPE`, and
465 contains a permutation.
466* The element(s) of `PAD` are used to fill out the result once `SOURCE`
467 has been consumed.
468
469```
peter klausler9849cf52018-09-25 21:47:55470SPREAD(any SOURCE, DIM, scalar INTEGER(any) NCOPIES) -> same type as SOURCE, rank=RANK(SOURCE)+1
peter klauslerbab1f672018-09-26 17:42:55471TRANSFER(any SOURCE, any MOLD) -> scalar if MOLD is scalar, else vector; same type and kind as MOLD
472TRANSFER(any SOURCE, any MOLD, scalar INTEGER(any) SIZE) -> vector(SIZE) of type and kind of MOLD
peter klausler9849cf52018-09-25 21:47:55473TRANSPOSE(any MATRIX(n,m)) -> matrix(m,n) of same type and kind as MATRIX
peter klausler3cecff62018-09-25 20:26:35474```
475
peter klausler9849cf52018-09-25 21:47:55476The shape of the result of `SPREAD` is the same as that of `SOURCE`, with `NCOPIES` inserted
477at position `DIM`.
478
peter klausler3cecff62018-09-25 20:26:35479```
peter klausler9849cf52018-09-25 21:47:55480UNPACK(any VECTOR(n), LOGICAL(any) MASK(..), FIELD) -> type and kind of VECTOR, shape of MASK
peter klausler3cecff62018-09-25 20:26:35481```
482`FIELD` has same type and kind as `VECTOR` and is conformable with `MASK`.
483
Richard Barton271a7bb2020-09-11 13:17:19484### Other transformational intrinsic functions
peter klausler9849cf52018-09-25 21:47:55485```
486BESSEL_JN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0))
487BESSEL_YN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0))
488COMMAND_ARGUMENT_COUNT() -> scalar default INTEGER
489DOT_PRODUCT(LOGICAL(k) VECTOR_A(n), LOGICAL(k) VECTOR_B(n)) -> LOGICAL(k) = ANY(VECTOR_A .AND. VECTOR_B)
490DOT_PRODUCT(COMPLEX(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(CONJG(VECTOR_A) * VECTOR_B)
491DOT_PRODUCT(INTEGER(any) or REAL(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(VECTOR_A * VECTOR_B)
492MATMUL(numeric ARRAY_A(j), numeric ARRAY_B(j,k)) -> numeric vector(k)
493MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k)) -> numeric vector(j)
494MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k,m)) -> numeric matrix(j,m)
495MATMUL(LOGICAL(n1) ARRAY_A(j), LOGICAL(n2) ARRAY_B(j,k)) -> LOGICAL vector(k)
496MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k)) -> LOGICAL vector(j)
497MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k,m)) -> LOGICAL matrix(j,m)
498NULL([POINTER/ALLOCATABLE MOLD]) -> POINTER
peter klauslerbab1f672018-09-26 17:42:55499REDUCE(any ARRAY(..), function OPERATION [, DIM, LOGICAL(any) MASK(..), IDENTITY, LOGICAL ORDERED=.FALSE. ])
peter klausler9849cf52018-09-25 21:47:55500REPEAT(CHARACTER(k,n) STRING, INTEGER(any) NCOPIES) -> CHARACTER(k,n*NCOPIES)
501SELECTED_CHAR_KIND('DEFAULT' or 'ASCII' or 'ISO_10646' or ...) -> scalar default INTEGER
502SELECTED_INT_KIND(scalar INTEGER(any) R) -> scalar default INTEGER
503SELECTED_REAL_KIND([scalar INTEGER(any) P, scalar INTEGER(any) R, scalar INTEGER(any) RADIX]) -> scalar default INTEGER
peter klauslerbab1f672018-09-26 17:42:55504SHAPE(SOURCE, KIND=KIND(0)) -> INTEGER(KIND)(RANK(SOURCE))
peter klausler9849cf52018-09-25 21:47:55505TRIM(CHARACTER(k,n) STRING) -> CHARACTER(k)
506```
peter klausler3cecff62018-09-25 20:26:35507
peter klausler9849cf52018-09-25 21:47:55508The type and kind of the result of a numeric `MATMUL` is the same as would result from
509a multiplication of an element of ARRAY_A and an element of ARRAY_B.
peter klausler3cecff62018-09-25 20:26:35510
peter klausler9849cf52018-09-25 21:47:55511The kind of the `LOGICAL` result of a `LOGICAL` `MATMUL` is the same as would result
512from an intrinsic `.AND.` operation between an element of `ARRAY_A` and an element
513of `ARRAY_B`.
peter klausler3cecff62018-09-25 20:26:35514
peter klausler9849cf52018-09-25 21:47:55515Note that `DOT_PRODUCT` with a `COMPLEX` first argument operates on its complex conjugate,
516but that `MATMUL` with a `COMPLEX` argument does not.
peter klausler3cecff62018-09-25 20:26:35517
peter klausler9849cf52018-09-25 21:47:55518The `MOLD` argument to `NULL` may be omitted only in a context where the type of the pointer is known,
519such as an initializer or pointer assignment statement.
peter klausler3cecff62018-09-25 20:26:35520
peter klausler9849cf52018-09-25 21:47:55521At least one argument must be present in a call to `SELECTED_REAL_KIND`.
peter klausler3cecff62018-09-25 20:26:35522
peter klausler9849cf52018-09-25 21:47:55523An assumed-rank array may be passed to `SHAPE`, and if it is associated with an assumed-size array,
524the last element of the result will be -1.
peter klausler3cecff62018-09-25 20:26:35525
Richard Barton271a7bb2020-09-11 13:17:19526### Coarray transformational intrinsic functions
peter klausler9849cf52018-09-25 21:47:55527```
528FAILED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector
529GET_TEAM([scalar INTEGER(?) LEVEL]) -> scalar TEAM_TYPE
530IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n) [, scalar TEAM_TYPE TEAM ]) -> scalar default INTEGER
531IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n), scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER
532NUM_IMAGES([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER
533NUM_IMAGES(scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER
534STOPPED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector
535TEAM_NUMBER([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER
536THIS_IMAGE([COARRAY, DIM, scalar TEAM_TYPE TEAM]) -> default INTEGER
537```
538The result of `THIS_IMAGE` is a scalar if `DIM` is present or if `COARRAY` is absent,
539and a vector whose length is the corank of `COARRAY` otherwise.
540
Richard Barton271a7bb2020-09-11 13:17:19541## Inquiry intrinsic functions
peter klauslere7c5a4702018-09-25 22:23:01542These are neither elemental nor transformational; all are pure.
543
Richard Barton271a7bb2020-09-11 13:17:19544### Type inquiry intrinsic functions
peter klauslerad9aede2018-10-11 21:51:14545All of these functions return constants.
546The value of the argument is not used, and may well be undefined.
peter klausler9849cf52018-09-25 21:47:55547```
548BIT_SIZE(INTEGER(k) I(..)) -> INTEGER(k)
549DIGITS(INTEGER or REAL X(..)) -> scalar default INTEGER
550EPSILON(REAL(k) X(..)) -> scalar REAL(k)
551HUGE(INTEGER(k) X(..)) -> scalar INTEGER(k)
552HUGE(REAL(k) X(..)) -> scalar of REAL(k)
553KIND(intrinsic X(..)) -> scalar default INTEGER
554MAXEXPONENT(REAL(k) X(..)) -> scalar default INTEGER
555MINEXPONENT(REAL(k) X(..)) -> scalar default INTEGER
556NEW_LINE(CHARACTER(k,n) A(..)) -> scalar CHARACTER(k,1) = CHAR(10)
peter klauslerad9aede2018-10-11 21:51:14557PRECISION(REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER
558RADIX(INTEGER(k) or REAL(k) X(..)) -> scalar default INTEGER, always 2
559RANGE(INTEGER(k) or REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER
peter klausler9849cf52018-09-25 21:47:55560TINY(REAL(k) X(..)) -> scalar REAL(k)
561```
562
Richard Barton271a7bb2020-09-11 13:17:19563### Bound and size inquiry intrinsic functions
peter klausler9849cf52018-09-25 21:47:55564The results are scalar when `DIM` is present, and a vector of length=(co)rank(`(CO)ARRAY`)
565when `DIM` is absent.
566```
567LBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
568LCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
569SIZE(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
570UBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
571UCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
572```
573
574Assumed-rank arrays may be used with `LBOUND`, `SIZE`, and `UBOUND`.
575
Richard Barton271a7bb2020-09-11 13:17:19576### Object characteristic inquiry intrinsic functions
peter klausler9849cf52018-09-25 21:47:55577```
578ALLOCATED(any type ALLOCATABLE ARRAY) -> scalar default LOGICAL
579ALLOCATED(any type ALLOCATABLE SCALAR) -> scalar default LOGICAL
580ASSOCIATED(any type POINTER POINTER [, same type TARGET]) -> scalar default LOGICAL
peter klauslerbab1f672018-09-26 17:42:55581COSHAPE(COARRAY, KIND=KIND(0)) -> INTEGER(KIND) vector of length corank(COARRAY)
peter klausler9849cf52018-09-25 21:47:55582EXTENDS_TYPE_OF(A, MOLD) -> default LOGICAL
583IS_CONTIGUOUS(any data ARRAY(..)) -> scalar default LOGICAL
584PRESENT(OPTIONAL A) -> scalar default LOGICAL
585RANK(any data A) -> scalar default INTEGER = 0 if A is scalar, SIZE(SHAPE(A)) if A is an array, rank if assumed-rank
586SAME_TYPE_AS(A, B) -> scalar default LOGICAL
peter klauslerbab1f672018-09-26 17:42:55587STORAGE_SIZE(any data A, KIND=KIND(0)) -> INTEGER(KIND)
peter klausler9849cf52018-09-25 21:47:55588```
589The arguments to `EXTENDS_TYPE_OF` must be of extensible derived types or be unlimited polymorphic.
590
591An assumed-rank array may be used with `IS_CONTIGUOUS` and `RANK`.
592
Richard Barton271a7bb2020-09-11 13:17:19593## Intrinsic subroutines
peter klausler970e746c2018-09-25 22:36:00594
595(*TODO*: complete these descriptions)
596
Richard Barton271a7bb2020-09-11 13:17:19597### One elemental intrinsic subroutine
peter klausler9849cf52018-09-25 21:47:55598```
599INTERFACE
600 SUBROUTINE MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)
601 INTEGER(k1) :: FROM, TO
602 INTENT(IN) :: FROM
603 INTENT(INOUT) :: TO
604 INTEGER(k2), INTENT(IN) :: FROMPOS
605 INTEGER(k3), INTENT(IN) :: LEN
606 INTEGER(k4), INTENT(IN) :: TOPOS
607 END SUBROUTINE
608END INTERFACE
609```
610
Richard Barton271a7bb2020-09-11 13:17:19611### Non-elemental intrinsic subroutines
peter klausler9849cf52018-09-25 21:47:55612```
613CALL CPU_TIME(REAL INTENT(OUT) TIME)
614```
615The kind of `TIME` is not specified in the standard.
616
617```
peter klauslerad9aede2018-10-11 21:51:14618CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])
peter klausler9849cf52018-09-25 21:47:55619```
620* All arguments are `OPTIONAL` and `INTENT(OUT)`.
621* `DATE`, `TIME`, and `ZONE` are scalar default `CHARACTER`.
622* `VALUES` is a vector of at least 8 elements of `INTEGER(KIND >= 2)`.
623```
peter klausler3cecff62018-09-25 20:26:35624CALL EVENT_QUERY(EVENT, COUNT [, STAT])
625CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])
626CALL GET_COMMAND([COMMAND, LENGTH, STATUS, ERRMSG ])
627CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS, ERRMSG ])
628CALL GET_ENVIRONMENT_VARIABLE(NAME [, VALUE, LENGTH, STATUS, TRIM_NAME, ERRMSG ])
629CALL MOVE_ALLOC(ALLOCATABLE INTENT(INOUT) FROM, ALLOCATABLE INTENT(OUT) TO [, STAT, ERRMSG ])
630CALL RANDOM_INIT(LOGICAL(k1) INTENT(IN) REPEATABLE, LOGICAL(k2) INTENT(IN) IMAGE_DISTINCT)
631CALL RANDOM_NUMBER(REAL(k) INTENT(OUT) HARVEST(..))
632CALL RANDOM_SEED([SIZE, PUT, GET])
633CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])
peter klausler9849cf52018-09-25 21:47:55634```
peter klausler3cecff62018-09-25 20:26:35635
Richard Barton271a7bb2020-09-11 13:17:19636### Atomic intrinsic subroutines
peter klausler9849cf52018-09-25 21:47:55637```
peter klausler3cecff62018-09-25 20:26:35638CALL ATOMIC_ADD(ATOM, VALUE [, STAT=])
639CALL ATOMIC_AND(ATOM, VALUE [, STAT=])
640CALL ATOMIC_CAS(ATOM, OLD, COMPARE, NEW [, STAT=])
641CALL ATOMIC_DEFINE(ATOM, VALUE [, STAT=])
642CALL ATOMIC_FETCH_ADD(ATOM, VALUE, OLD [, STAT=])
643CALL ATOMIC_FETCH_AND(ATOM, VALUE, OLD [, STAT=])
644CALL ATOMIC_FETCH_OR(ATOM, VALUE, OLD [, STAT=])
645CALL ATOMIC_FETCH_XOR(ATOM, VALUE, OLD [, STAT=])
646CALL ATOMIC_OR(ATOM, VALUE [, STAT=])
647CALL ATOMIC_REF(VALUE, ATOM [, STAT=])
648CALL ATOMIC_XOR(ATOM, VALUE [, STAT=])
peter klausler9849cf52018-09-25 21:47:55649```
peter klausler3cecff62018-09-25 20:26:35650
Richard Barton271a7bb2020-09-11 13:17:19651### Collective intrinsic subroutines
peter klausler9849cf52018-09-25 21:47:55652```
peter klausler3cecff62018-09-25 20:26:35653CALL CO_BROADCAST
654CALL CO_MAX
655CALL CO_MIN
656CALL CO_REDUCE
657CALL CO_SUM
peter klausler9849cf52018-09-25 21:47:55658```
peter klausler370c44a2018-09-25 23:59:41659
Richard Barton271a7bb2020-09-11 13:17:19660## Non-standard intrinsics
661### PGI
peter klausler370c44a2018-09-25 23:59:41662```
663AND, OR, XOR
664LSHIFT, RSHIFT, SHIFT
665ZEXT, IZEXT
666COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D
667COMPL
668DCMPLX
669EQV, NEQV
670INT8
671JINT, JNINT, KNINT
672LOC
673```
674
Richard Barton271a7bb2020-09-11 13:17:19675### Intel
peter klausler370c44a2018-09-25 23:59:41676```
677DCMPLX(X,Y), QCMPLX(X,Y)
678DREAL(DOUBLE COMPLEX A) -> DOUBLE PRECISION
679DFLOAT, DREAL
680QEXT, QFLOAT, QREAL
681DNUM, INUM, JNUM, KNUM, QNUM, RNUM - scan value from string
682ZEXT
683RAN, RANF
684ILEN(I) = BIT_SIZE(I)
685SIZEOF
686MCLOCK, SECNDS
687COTAN(X) = 1.0/TAN(X)
688COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COTAND - degrees
689AND, OR, XOR
690LSHIFT, RSHIFT
691IBCHNG, ISHA, ISHC, ISHL, IXOR
692IARG, IARGC, NARGS, NUMARG
693BADDRESS, IADDR
694CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, LOC
695MALLOC
696```
peter klausler42b33da2018-09-29 00:02:11697
Yi Wu18af0322023-12-21 10:35:28698### Library subroutine
699```
Yi Wu959a4302024-01-11 12:15:48700CALL FDATE(TIME)
Yi Wu18af0322023-12-21 10:35:28701CALL GETLOG(USRNAME)
702```
703
Jean Perier878b5262020-10-26 10:25:40704## Intrinsic Procedure Name Resolution
705
706When the name of a procedure in a program is the same as the one of an intrinsic
707procedure, and nothing other than its usage allows to decide whether the procedure
708is the intrinsic or not (i.e, it does not appear in an INTRINSIC or EXTERNAL attribute
709statement, is not an use/host associated procedure...), Fortran 2018 standard
710section 19.5.1.4 point 6 rules that the procedure is established to be intrinsic if it is
711invoked as an intrinsic procedure.
712
713In case the invocation would be an error if the procedure were the intrinsic
714(e.g. wrong argument number or type), the broad wording of the standard
715leaves two choices to the compiler: emit an error about the intrinsic invocation,
716or consider this is an external procedure and emit no error.
717
718f18 will always consider this case to be the intrinsic and emit errors, unless the procedure
719is used as a function (resp. subroutine) and the intrinsic is a subroutine (resp. function).
720The table below gives some examples of decisions made by Fortran compilers in such case.
721
722| What is ACOS ? | Bad intrinsic call | External with warning | External no warning | Other error |
723| --- | --- | --- | --- | --- |
724| `print*, ACOS()` | gfortran, nag, xlf, f18 | ifort | nvfortran | |
725| `print*, ACOS(I)` | gfortran, nag, xlf, f18 | ifort | nvfortran | |
726| `print*, ACOS(X=I)` | gfortran, nag, xlf, f18 | ifort | | nvfortran (keyword on implicit extrenal )|
727| `print*, ACOS(X, X)` | gfortran, nag, xlf, f18 | ifort | nvfortran | |
728| `CALL ACOS(X)` | | | gfortran, nag, xlf, nvfortran, ifort, f18 | |
729
730
731The rationale for f18 behavior is that when referring to a procedure with an
732argument number or type that does not match the intrinsic specification, it seems safer to block
733the rather likely case where the user is using the intrinsic the wrong way.
734In case the user wanted to refer to an external function, he can add an explicit EXTERNAL
735statement with no other consequences on the program.
736However, it seems rather unlikely that a user would confuse an intrinsic subroutine for a
737function and vice versa. Given no compiler is issuing an error here, changing the behavior might
738affect existing programs that omit the EXTERNAL attribute in such case.
739
740Also note that in general, the standard gives the compiler the right to consider
741any procedure that is not explicitly external as a non standard intrinsic (section 4.2 point 4).
742So it is highly advised for the programmer to use EXTERNAL statements to prevent any ambiguity.
743
Richard Barton271a7bb2020-09-11 13:17:19744## Intrinsic Procedure Support in f18
Jean Perier3774e9d2019-03-29 15:48:39745This section gives an overview of the support inside f18 libraries for the
746intrinsic procedures listed above.
747It may be outdated, refer to f18 code base for the actual support status.
748
Richard Barton271a7bb2020-09-11 13:17:19749### Semantic Analysis
Jean Perier3774e9d2019-03-29 15:48:39750F18 semantic expression analysis phase detects intrinsic procedure references,
751validates the argument types and deduces the return types.
752This phase currently supports all the intrinsic procedures listed above but the ones in the table below.
753
754| Intrinsic Category | Intrinsic Procedures Lacking Support |
755| --- | --- |
Katherine Rasmussen8b389702024-01-31 00:01:02756| Coarray intrinsic functions | COSHAPE |
Jean Perier3774e9d2019-03-29 15:48:39757| Object characteristic inquiry functions | ALLOCATED, ASSOCIATED, EXTENDS_TYPE_OF, IS_CONTIGUOUS, PRESENT, RANK, SAME_TYPE, STORAGE_SIZE |
758| Type inquiry intrinsic functions | BIT_SIZE, DIGITS, EPSILON, HUGE, KIND, MAXEXPONENT, MINEXPONENT, NEW_LINE, PRECISION, RADIX, RANGE, TINY|
Yi Wude58aa82023-11-13 10:31:36759| Non-standard intrinsic functions | AND, OR, XOR, SHIFT, ZEXT, IZEXT, COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COMPL, EQV, NEQV, INT8, JINT, JNINT, KNINT, 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, GETPID, NUMARG, BADDRESS, IADDR, CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, MALLOC |
Yi Wu7c8ef762024-01-29 16:34:04760| 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, SIGNAL, SLEEP, SYSTEM, SYSTEM_CLOCK |
Katherine Rasmussenecedc4d2022-11-01 21:14:08761| Atomic intrinsic subroutines | ATOMIC_ADD |
Katherine Rasmussenbc2a85f2022-08-25 21:33:59762| Collective intrinsic subroutines | CO_REDUCE |
Yi Wu959a4302024-01-11 12:15:48763| Library subroutines | FDATE, GETLOG |
Jean Perier3774e9d2019-03-29 15:48:39764
765
Richard Barton271a7bb2020-09-11 13:17:19766### Intrinsic Function Folding
Jean Perier3774e9d2019-03-29 15:48:39767Fortran Constant Expressions can contain references to a certain number of
768intrinsic functions (see Fortran 2018 standard section 10.1.12 for more details).
769Constant Expressions may be used to define kind arguments. Therefore, the semantic
770expression analysis phase must be able to fold references to intrinsic functions
771listed in section 10.1.12.
772
773F18 intrinsic function folding is either performed by implementations directly
774operating on f18 scalar types or by using host runtime functions and
775host hardware types. F18 supports folding elemental intrinsic functions over
776arrays when an implementation is provided for the scalars (regardless of whether
777it is using host hardware types or not).
778The status of intrinsic function folding support is given in the sub-sections below.
779
Richard Barton271a7bb2020-09-11 13:17:19780#### Intrinsic Functions with Host Independent Folding Support
Jean Perier3774e9d2019-03-29 15:48:39781Implementations using f18 scalar types enables folding intrinsic functions
782on any host and with any possible type kind supported by f18. The intrinsic functions
783listed below are folded using host independent implementations.
784
785| Return Type | Intrinsic Functions with Host Independent Folding Support|
786| --- | --- |
787| 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 |
788| REAL | ABS(REAL(k)), ABS(COMPLEX(k)), AIMAG, AINT, DPROD, REAL |
789| COMPLEX | CMPLX, CONJG |
790| LOGICAL | BGE, BGT, BLE, BLT |
791
Richard Barton271a7bb2020-09-11 13:17:19792#### Intrinsic Functions with Host Dependent Folding Support
Jean Perierf9ab3212019-04-01 08:39:19793Implementations using the host runtime may not be available for all supported
794f18 types depending on the host hardware types and the libraries available on the host.
Jean Perier3774e9d2019-03-29 15:48:39795The actual support on a host depends on what the host hardware types are.
796The list below gives the functions that are folded using host runtime and the related C/C++ types.
797F18 automatically detects if these types match an f18 scalar type. If so,
798folding of the intrinsic functions will be possible for the related f18 scalar type,
Jean Perierf9ab3212019-04-01 08:39:19799otherwise an error message will be produced by f18 when attempting to fold related intrinsic functions.
Jean Perier3774e9d2019-03-29 15:48:39800
801| C/C++ Host Type | Intrinsic Functions with Host Standard C++ Library Based Folding Support |
802| --- | --- |
803| 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 |
804| std::complex for float, double and long double| ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH, COS, COSH, EXP, LOG, SIN, SINH, SQRT, TAN, TANH |
805
806On top of the default usage of C++ standard library functions for folding described
807in the table above, it is possible to compile f18 evaluate library with
808[libpgmath](https://github.com/flang-compiler/flang/tree/master/runtime/libpgmath)
809so that it can be used for folding. To do so, one must have a compiled version
810of the libpgmath library available on the host and add
811`-DLIBPGMATH_DIR=<path to the compiled shared libpgmath library>` to the f18 cmake command.
812
813Libpgmath comes with real and complex functions that replace C++ standard library
814float and double functions to fold all the intrinsic functions listed in the table above.
815It has no long double versions. If the host long double matches an f18 scalar type,
816C++ standard library functions will still be used for folding expressions with this scalar type.
817Libpgmath adds the possibility to fold the following functions for f18 real scalar
818types related to host float and double types.
819
820| C/C++ Host Type | Additional Intrinsic Function Folding Support with Libpgmath (Optional) |
821| --- | --- |
822|float and double| BESSEL_J0, BESSEL_J1, BESSEL_JN (elemental only), BESSEL_Y0, BESSEL_Y1, BESSEL_Yn (elemental only), ERFC_SCALED |
823
jeanPerier5d18a302019-04-03 08:26:46824Libpgmath comes in three variants (precise, relaxed and fast). So far, only the
Jean Perier3774e9d2019-03-29 15:48:39825precise version is used for intrinsic function folding in f18. It guarantees the greatest numerical precision.
826
827### Intrinsic Functions with Missing Folding Support
828The following intrinsic functions are allowed in constant expressions but f18
829is not yet able to fold them. Note that there might be constraints on the arguments
830so that these intrinsics can be used in constant expressions (see section 10.1.12 of Fortran 2018 standard).
831
832ALL, ACHAR, ADJUSTL, ADJUSTR, ANINT, ANY, BESSEL_JN (transformational only),
833BESSEL_YN (transformational only), BTEST, CEILING, CHAR, COUNT, CSHIFT, DOT_PRODUCT,
834DIM (REAL only), DOT_PRODUCT, EOSHIFT, FINDLOC, FLOOR, FRACTION, HUGE, IACHAR, IALL,
835IANY, IPARITY, IBITS, ICHAR, IMAGE_STATUS, INDEX, ISHFTC, IS_IOSTAT_END,
836IS_IOSTAT_EOR, LBOUND, LEN_TRIM, LGE, LGT, LLE, LLT, LOGICAL, MATMUL, MAX, MAXLOC,
837MAXVAL, MERGE, MIN, MINLOC, MINVAL, MOD (INTEGER only), MODULO, NEAREST, NINT,
838NORM2, NOT, OUT_OF_RANGE, PACK, PARITY, PRODUCT, REPEAT, REDUCE, RESHAPE,
839RRSPACING, SCAN, SCALE, SELECTED_CHAR_KIND, SELECTED_INT_KIND, SELECTED_REAL_KIND,
840SET_EXPONENT, SHAPE, SIGN, SIZE, SPACING, SPREAD, SUM, TINY, TRANSFER, TRANSPOSE,
841TRIM, UBOUND, UNPACK, VERIFY.
842
843Coarray, non standard, IEEE and ISO_C_BINDINGS intrinsic functions that can be
844used in constant expressions have currently no folding support at all.
Yi Wue2b896a2024-01-10 10:02:48845
846### Standard Intrinsics: EXECUTE_COMMAND_LINE
847
848#### Usage and Info
849
Yi Wu7dd4d282024-01-13 01:22:40850- **Standard:** Fortran 2008 and later, specified in subclause 16.9.73
Yi Wue2b896a2024-01-10 10:02:48851- **Class:** Subroutine
852- **Syntax:** `CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])`
853- **Arguments:**
854
Yi Wu14a15102024-01-29 11:13:25855| Argument | Description |
856|------------|-----------------------------------------------------------------------|
857| `COMMAND` | Shall be a default CHARACTER scalar. |
858| `WAIT` | (Optional) Shall be a default LOGICAL scalar. |
859| `EXITSTAT` | (Optional) Shall be an INTEGER with kind greater than or equal to 4. |
860| `CMDSTAT` | (Optional) Shall be an INTEGER with kind greater than or equal to 2. |
861| `CMDMSG` | (Optional) Shall be a CHARACTER scalar of the default kind. |
Yi Wue2b896a2024-01-10 10:02:48862
863#### Implementation Specifics
864
Yi Wu7dd4d282024-01-13 01:22:40865##### `COMMAND`:
Yi Wue2b896a2024-01-10 10:02:48866
Yi Wu7dd4d282024-01-13 01:22:40867- Must be preset.
Yi Wue2b896a2024-01-10 10:02:48868
Yi Wu7dd4d282024-01-13 01:22:40869##### `WAIT`:
870
871- If set to `false`, the command is executed asynchronously.
872- If not preset or set to `true`, it is executed synchronously.
873- Synchronous execution is achieved by passing the command into `std::system` on all systems.
874- Asynchronous execution is achieved by calling `fork()` on POSIX-compatible systems or `CreateProcess()` on Windows.
875
876##### `EXITSTAT`:
877
878- Synchronous execution:
879 - Inferred by the return value of `std::system(cmd)`.
880 - On POSIX-compatible systems: return value is first passed into `WEXITSTATUS(status)`, then assigned to `EXITSTAT`.
881 - On Windows, the value is directly assigned as the return value of `std::system()`.
882- Asynchronous execution:
883 - Value is not modified.
884
885##### `CMDSTAT`:
886
887- Synchronous execution:
Yi Wue2b896a2024-01-10 10:02:48888 - -2: No error condition occurs, but `WAIT` is present with the value `false`, and the processor does not support asynchronous execution.
889 - -1: The processor does not support command line execution.
890 - \+ (positive value): An error condition occurs.
Yi Wu7dd4d282024-01-13 01:22:40891 - 1: Fork Error (occurs only on POSIX-compatible systems).
892 - 2: Execution Error (command exits with status -1).
893 - 3: Invalid Command Error (determined by the exit code depending on the system).
894 - On Windows: exit code is 1.
895 - On POSIX-compatible systems: exit code is 127 or 126.
896 - 4: Signal error (either stopped or killed by signal, occurs only on POSIX-compatible systems).
Yi Wue2b896a2024-01-10 10:02:48897 - 0: Otherwise.
Yi Wu7dd4d282024-01-13 01:22:40898- Asynchronous execution:
899 - 0 will always be assigned.
Yi Wue2b896a2024-01-10 10:02:48900
Yi Wu7dd4d282024-01-13 01:22:40901##### `CMDMSG`:
902
903- Synchronous execution:
904 - If an error condition occurs, it is assigned an explanatory message; otherwise, it remains unchanged.
905 - If a condition occurs that would assign a nonzero value to `CMDSTAT` but the `CMDSTAT` variable is not present, error termination is initiated (applies to both POSIX-compatible systems and Windows).
906- Asynchronous execution:
907 - The value is unchanged.
Yi Wue2b896a2024-01-10 10:02:48908 - If a condition occurs that would assign a nonzero value to `CMDSTAT` but the `CMDSTAT` variable is not present, error termination is initiated.
Yi Wu7dd4d282024-01-13 01:22:40909 - On POSIX-compatible systems, the child process (async process) will be terminated with no effect on the parent process (continues).
910 - On Windows, error termination is not initiated.