3 Free Software Foundation, Inc.
4 This is part of the GFORTRAN manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``GNU General Public License'' and ``Funding
11 Free Software'', the Front-Cover texts being (a) (see below), and with
12 the Back-Cover Texts being (b) (see below). A copy of the license is
13 included in the gfdl(7) man page.
16 Some basic guidelines for editing this document:
18 (1) The intrinsic procedures are to be listed in alphabetical order.
19 (2) The generic name is to be use.
20 (3) The specific names are included in the function index and in a
21 table at the end of the node (See ABS entry).
22 (4) Try to maintain the same style for each entry.
27 @node Intrinsic Procedures
28 @chapter Intrinsic Procedures
29 @cindex Intrinsic Procedures
31 This portion of the document is incomplete and undergoing massive expansion
32 and editing. All contributions and corrections are strongly encouraged.
35 * Introduction: Introduction
36 * @code{ABORT}: ABORT, Abort the program
37 * @code{ABS}: ABS, Absolute value
38 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
39 * @code{ACOS}: ACOS, Arccosine function
40 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
41 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
42 * @code{AIMAG}: AIMAG, Imaginary part of complex number
43 * @code{AINT}: AINT, Truncate to a whole number
44 * @code{ALL}: ALL, Determine all values are true
48 @section Introduction to intrinsic procedures
50 Gfortran provides a rich set of intrinsic procedures that includes all
51 the intrinsic procedures required by the Fortran 95 standard, a set of
52 intrinsic procedures for backwards compatibility with Gnu Fortran 77
53 (i.e., @command{g77}), and a small selection of intrinsic procedures
54 from the Fortran 2003 standard. Any description here, which conflicts with a
55 description in either the Fortran 95 standard or the Fortran 2003 standard,
56 is unintentional and the standard(s) should be considered authoritative.
58 The enumeration of the @code{KIND} type parameter is processor defined in
59 the Fortran 95 standard. Gfortran defines the default integer type and
60 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
61 respectively. The standard mandates that both data types shall have
62 another kind, which have more precision. On typical target architectures
63 supports by @command{gfortran}, this kind type parameter is @code{KIND=8}.
64 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
65 In the description of generic intrinsic procedures, the kind type parameter
66 will be specified by @code{KIND=*}, and in the description of specific
67 names for an intrinsic procedure the kind type parameter will be explicitly
68 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
69 brevity the optional @code{KIND=} syntax will be omitted.
71 Many of the intrinsics procedures take one or more optional arguments.
72 This document follows the convention used in the Fortran 95 standard,
73 and denotes such arguments by square brackets.
75 @command{Gfortran} offers the @option{-std=f95} and @option{-std=gnu} options,
76 which can be used to restrict the set of intrinsic procedures to a
77 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
78 option, and so all intrinsic procedures describe here are accepted. There
79 is one caveat. For a select group of intrinsic procedures, @command{g77}
80 implemented both a function and a subroutine. Both classes
81 have been implemented in @command{gfortran} for backwards compatibility
82 with @command{g77}. It is noted here that these functions and subroutines
83 cannot be intermixed in a given subprogram. In the descriptions that follow,
84 the applicable option(s) is noted.
89 @section @code{ABORT} --- Abort the program
94 @item @emph{Description}:
95 @code{ABORT} causes immediate termination of the program. On operating
96 systems that support a core dump, @code{ABORT} will produce a core dump,
97 which is suitable for debugging purposes.
103 non-elemental subroutine
108 @item @emph{Return value}:
111 @item @emph{Example}:
114 integer :: i = 1, j = 2
115 if (i /= j) call abort
116 end program test_abort
123 @section @code{ABS} --- Absolute value
124 @findex @code{ABS} intrinsic
125 @findex @code{CABS} intrinsic
126 @findex @code{DABS} intrinsic
127 @findex @code{IABS} intrinsic
128 @findex @code{ZABS} intrinsic
129 @findex @code{CDABS} intrinsic
130 @cindex absolute value
133 @item @emph{Description}:
134 @code{ABS(X)} computes the absolute value of @code{X}.
145 @item @emph{Arguments}:
146 @multitable @columnfractions .15 .80
147 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
148 @code{REAL(*)}, or @code{COMPLEX(*)}.
151 @item @emph{Return value}:
152 The return value is of the same type and
153 kind as the argument except the return value is @code{REAL(*)} for a
154 @code{COMPLEX(*)} argument.
156 @item @emph{Example}:
161 complex :: z = (-1.e0,0.e0)
165 end program test_abort
168 @item @emph{Specific names}:
169 @multitable @columnfractions .24 .24 .24 .24
170 @item Name @tab Argument @tab Return type @tab Option
171 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab f95, gnu
172 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
173 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab f95, gnu
174 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
175 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
182 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
183 @findex @code{ACHAR} intrinsic
184 @cindex @acronym{ASCII} collating sequence
187 @item @emph{Description}:
188 @code{ACHAR(I)} returns the character located at position @code{I}
189 in the @acronym{ASCII} collating sequence.
200 @item @emph{Arguments}:
201 @multitable @columnfractions .15 .80
202 @item @var{I} @tab The type shall be an @code{INTEGER(*)}.
205 @item @emph{Return value}:
206 The return value is of type @code{CHARACTER} with a length of one. The
207 kind type parameter is the same as @code{KIND('A')}.
209 @item @emph{Example}:
214 end program test_abort
221 @section @code{ACOS} --- Arccosine function
222 @findex @code{ACOS} intrinsic
223 @findex @code{DACOS} intrinsic
227 @item @emph{Description}:
228 @code{ACOS(X)} computes the arccosine of its @var{X}.
239 @item @emph{Arguments}:
240 @multitable @columnfractions .15 .80
241 @item @var{X} @tab The type shall be an @code{REAL(*)}.
244 @item @emph{Return value}:
245 The return value is of type @code{REAL(*)} and it lies in the
246 range @math{ 0 \leq \arccos (x) \leq \pi}.
248 @item @emph{Example}:
251 real(8) :: x = 0.866_8
253 end program test_acos
256 @item @emph{Specific names}:
257 @multitable @columnfractions .24 .24 .24 .24
258 @item Name @tab Argument @tab Return type @tab Option
259 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
266 @section @code{ADJUSTL} --- Left adjust a string
267 @findex @code{ADJUSTL} intrinsic
268 @cindex adjust string
271 @item @emph{Description}:
272 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
273 Spaces are inserted at the end of the string as needed.
282 @code{STR = ADJUSTL(STR)}
284 @item @emph{Arguments}:
285 @multitable @columnfractions .15 .80
286 @item @var{STR} @tab The type shall be @code{CHARACTER}.
289 @item @emph{Return value}:
290 The return value is of type @code{CHARACTER} where leading spaces
291 are removed and the same number of spaces are inserted on the end
294 @item @emph{Example}:
297 character(len=20) :: str = ' gfortran'
300 end program test_adjustl
306 @section @code{ADJUSTR} --- Right adjust a string
307 @findex @code{ADJUSTR} intrinsic
308 @cindex adjust string
311 @item @emph{Description}:
312 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
313 Spaces are inserted at the start of the string as needed.
322 @code{STR = ADJUSTR(STR)}
324 @item @emph{Arguments}:
325 @multitable @columnfractions .15 .80
326 @item @var{STR} @tab The type shall be @code{CHARACTER}.
329 @item @emph{Return value}:
330 The return value is of type @code{CHARACTER} where trailing spaces
331 are removed and the same number of spaces are inserted at the start
334 @item @emph{Example}:
337 character(len=20) :: str = 'gfortran'
340 end program test_adjustr
346 @section @code{AIMAG} --- Imaginary part of complex number
347 @findex @code{AIMAG} intrinsic
348 @findex @code{DIMAG} intrinsic
349 @cindex Imaginary part
352 @item @emph{Description}:
353 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
364 @item @emph{Arguments}:
365 @multitable @columnfractions .15 .80
366 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
369 @item @emph{Return value}:
370 The return value is of type real with the
371 kind type parameter of the argument.
373 @item @emph{Example}:
378 z4 = cmplx(1.e0_4, 0.e0_4)
379 z8 = cmplx(0.e0_8, 1.e0_8)
380 print *, aimag(z4), dimag(z8)
381 end program test_aimag
384 @item @emph{Specific names}:
385 @multitable @columnfractions .24 .24 .24 .24
386 @item Name @tab Argument @tab Return type @tab Option
387 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab f95, gnu
393 @section @code{AINT} --- Imaginary part of complex number
394 @findex @code{AINT} intrinsic
395 @findex @code{DINT} intrinsic
399 @item @emph{Description}:
400 @code{AINT(X [, KIND])} truncates its argument to a whole number.
409 @code{X = AINT(X)} @*
410 @code{X = AINT(X, KIND)}
412 @item @emph{Arguments}:
413 @multitable @columnfractions .15 .80
414 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
415 @item @var{KIND} @tab (Optional) @var{KIND} shall be a scalar integer
416 initialization expression.
419 @item @emph{Return value}:
420 The return value is of type real with the kind type parameter of the
421 argument if the optional @var{KIND} is absence; otherwise, the kind
422 type parameter will be given by @var{KIND}. If the magnitude of
423 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
424 magnitude is equal to or greater than one, then it returns the largest
425 whole number that does not exceed its magnitude. The sign is the same
426 as the sign of @var{X}.
428 @item @emph{Example}:
435 print *, aint(x4), dint(x8)
437 end program test_aint
440 @item @emph{Specific names}:
441 @multitable @columnfractions .24 .24 .24 .24
442 @item Name @tab Argument @tab Return type @tab Option
443 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
449 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
450 @findex @code{ALL} intrinsic
454 @item @emph{Description}:
455 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
456 in the array along dimension @var{DIM}.
462 transformational function
465 @code{L = ALL(MASK)} @*
466 @code{L = ALL(MASK, DIM)}
468 @item @emph{Arguments}:
469 @multitable @columnfractions .15 .80
470 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
471 it shall not be scalar.
472 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
473 with a value that lies between one and the rank of @var{MASK}.
476 @item @emph{Return value}:
477 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
478 the kind type parameter is the same as the kind type parameter of
479 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
480 an array with the rank of @var{MASK} minus 1. The shape is determined from
481 the shape of @var{MASK} where the @var{DIM} dimension is elided.
485 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
486 It also is true if @var{MASK} has zero size; otherwise, it is false.
488 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
489 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
490 is determined by applying @code{ALL} to the array sections.
493 @item @emph{Example}:
497 l = all((/.true., .true., .true./))
502 integer a(2,3), b(2,3)
506 print *, all(a .eq. b, 1)
507 print *, all(a .eq. b, 2)
508 end subroutine section
513 @comment gen allocated
523 @comment gen associated
549 @comment gen bit_size
559 @comment gen command_argument_count
574 @comment sub cpu_time
578 @comment sub date_and_time
591 @comment gen dot_product
619 @comment gen exponent
627 @comment gen fraction
645 @comment sub get_command
647 @comment sub get_command_argument
649 @comment sub get_environment_variable
689 @comment gen len_trim
720 @comment gen maxexponent
735 @comment gen minexponent
760 @comment gen precision
771 @comment sub random_number
773 @comment sub random_seed
785 @comment gen rrspacing
794 @comment gen selected_int_kind
796 @comment gen selected_real_kind
798 @comment gen set_exponent
823 @comment zsqrt,cdsqrt
835 @comment sub system_clock
845 @comment gen transfer
847 @comment gen transpose