|
221
|
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.
|
