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 if all values are true
45 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
46 * @code{ANINT}: ANINT, Nearest whole number
47 * @code{ANY}: ANY, Determine if any values are true
48 * @code{ASIN}: ASIN, Arcsine function
52 @section Introduction to intrinsic procedures
54 Gfortran provides a rich set of intrinsic procedures that includes all
55 the intrinsic procedures required by the Fortran 95 standard, a set of
56 intrinsic procedures for backwards compatibility with Gnu Fortran 77
57 (i.e., @command{g77}), and a small selection of intrinsic procedures
58 from the Fortran 2003 standard. Any description here, which conflicts with a
59 description in either the Fortran 95 standard or the Fortran 2003 standard,
60 is unintentional and the standard(s) should be considered authoritative.
62 The enumeration of the @code{KIND} type parameter is processor defined in
63 the Fortran 95 standard. Gfortran defines the default integer type and
64 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
65 respectively. The standard mandates that both data types shall have
66 another kind, which have more precision. On typical target architectures
67 supports by @command{gfortran}, this kind type parameter is @code{KIND=8}.
68 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
69 In the description of generic intrinsic procedures, the kind type parameter
70 will be specified by @code{KIND=*}, and in the description of specific
71 names for an intrinsic procedure the kind type parameter will be explicitly
72 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
73 brevity the optional @code{KIND=} syntax will be omitted.
75 Many of the intrinsics procedures take one or more optional arguments.
76 This document follows the convention used in the Fortran 95 standard,
77 and denotes such arguments by square brackets.
79 @command{Gfortran} offers the @option{-std=f95} and @option{-std=gnu} options,
80 which can be used to restrict the set of intrinsic procedures to a
81 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
82 option, and so all intrinsic procedures describe here are accepted. There
83 is one caveat. For a select group of intrinsic procedures, @command{g77}
84 implemented both a function and a subroutine. Both classes
85 have been implemented in @command{gfortran} for backwards compatibility
86 with @command{g77}. It is noted here that these functions and subroutines
87 cannot be intermixed in a given subprogram. In the descriptions that follow,
88 the applicable option(s) is noted.
93 @section @code{ABORT} --- Abort the program
98 @item @emph{Description}:
99 @code{ABORT} causes immediate termination of the program. On operating
100 systems that support a core dump, @code{ABORT} will produce a core dump,
101 which is suitable for debugging purposes.
107 non-elemental subroutine
112 @item @emph{Return value}:
115 @item @emph{Example}:
118 integer :: i = 1, j = 2
119 if (i /= j) call abort
120 end program test_abort
127 @section @code{ABS} --- Absolute value
128 @findex @code{ABS} intrinsic
129 @findex @code{CABS} intrinsic
130 @findex @code{DABS} intrinsic
131 @findex @code{IABS} intrinsic
132 @findex @code{ZABS} intrinsic
133 @findex @code{CDABS} intrinsic
134 @cindex absolute value
137 @item @emph{Description}:
138 @code{ABS(X)} computes the absolute value of @code{X}.
149 @item @emph{Arguments}:
150 @multitable @columnfractions .15 .80
151 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
152 @code{REAL(*)}, or @code{COMPLEX(*)}.
155 @item @emph{Return value}:
156 The return value is of the same type and
157 kind as the argument except the return value is @code{REAL(*)} for a
158 @code{COMPLEX(*)} argument.
160 @item @emph{Example}:
165 complex :: z = (-1.e0,0.e0)
172 @item @emph{Specific names}:
173 @multitable @columnfractions .24 .24 .24 .24
174 @item Name @tab Argument @tab Return type @tab Option
175 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab f95, gnu
176 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
177 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab f95, gnu
178 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
179 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
186 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
187 @findex @code{ACHAR} intrinsic
188 @cindex @acronym{ASCII} collating sequence
191 @item @emph{Description}:
192 @code{ACHAR(I)} returns the character located at position @code{I}
193 in the @acronym{ASCII} collating sequence.
204 @item @emph{Arguments}:
205 @multitable @columnfractions .15 .80
206 @item @var{I} @tab The type shall be an @code{INTEGER(*)}.
209 @item @emph{Return value}:
210 The return value is of type @code{CHARACTER} with a length of one. The
211 kind type parameter is the same as @code{KIND('A')}.
213 @item @emph{Example}:
218 end program test_achar
225 @section @code{ACOS} --- Arccosine function
226 @findex @code{ACOS} intrinsic
227 @findex @code{DACOS} intrinsic
231 @item @emph{Description}:
232 @code{ACOS(X)} computes the arccosine of its @var{X}.
243 @item @emph{Arguments}:
244 @multitable @columnfractions .15 .80
245 @item @var{X} @tab The type shall be an @code{REAL(*)}, and a magnitude that is
249 @item @emph{Return value}:
250 The return value is of type @code{REAL(*)} and it lies in the
251 range @math{ 0 \leq \arccos (x) \leq \pi}. The kind type
252 parameter is the same as @var{X}.
254 @item @emph{Example}:
257 real(8) :: x = 0.866_8
259 end program test_acos
262 @item @emph{Specific names}:
263 @multitable @columnfractions .24 .24 .24 .24
264 @item Name @tab Argument @tab Return type @tab Option
265 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
272 @section @code{ADJUSTL} --- Left adjust a string
273 @findex @code{ADJUSTL} intrinsic
274 @cindex adjust string
277 @item @emph{Description}:
278 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
279 Spaces are inserted at the end of the string as needed.
288 @code{STR = ADJUSTL(STR)}
290 @item @emph{Arguments}:
291 @multitable @columnfractions .15 .80
292 @item @var{STR} @tab The type shall be @code{CHARACTER}.
295 @item @emph{Return value}:
296 The return value is of type @code{CHARACTER} where leading spaces
297 are removed and the same number of spaces are inserted on the end
300 @item @emph{Example}:
303 character(len=20) :: str = ' gfortran'
306 end program test_adjustl
312 @section @code{ADJUSTR} --- Right adjust a string
313 @findex @code{ADJUSTR} intrinsic
314 @cindex adjust string
317 @item @emph{Description}:
318 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
319 Spaces are inserted at the start of the string as needed.
328 @code{STR = ADJUSTR(STR)}
330 @item @emph{Arguments}:
331 @multitable @columnfractions .15 .80
332 @item @var{STR} @tab The type shall be @code{CHARACTER}.
335 @item @emph{Return value}:
336 The return value is of type @code{CHARACTER} where trailing spaces
337 are removed and the same number of spaces are inserted at the start
340 @item @emph{Example}:
343 character(len=20) :: str = 'gfortran'
346 end program test_adjustr
352 @section @code{AIMAG} --- Imaginary part of complex number
353 @findex @code{AIMAG} intrinsic
354 @findex @code{DIMAG} intrinsic
355 @cindex Imaginary part
358 @item @emph{Description}:
359 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
370 @item @emph{Arguments}:
371 @multitable @columnfractions .15 .80
372 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
375 @item @emph{Return value}:
376 The return value is of type real with the
377 kind type parameter of the argument.
379 @item @emph{Example}:
384 z4 = cmplx(1.e0_4, 0.e0_4)
385 z8 = cmplx(0.e0_8, 1.e0_8)
386 print *, aimag(z4), dimag(z8)
387 end program test_aimag
390 @item @emph{Specific names}:
391 @multitable @columnfractions .24 .24 .24 .24
392 @item Name @tab Argument @tab Return type @tab Option
393 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab f95, gnu
399 @section @code{AINT} --- Imaginary part of complex number
400 @findex @code{AINT} intrinsic
401 @findex @code{DINT} intrinsic
405 @item @emph{Description}:
406 @code{AINT(X [, KIND])} truncates its argument to a whole number.
415 @code{X = AINT(X)} @*
416 @code{X = AINT(X, KIND)}
418 @item @emph{Arguments}:
419 @multitable @columnfractions .15 .80
420 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
421 @item @var{KIND} @tab (Optional) @var{KIND} shall be a scalar integer
422 initialization expression.
425 @item @emph{Return value}:
426 The return value is of type real with the kind type parameter of the
427 argument if the optional @var{KIND} is absence; otherwise, the kind
428 type parameter will be given by @var{KIND}. If the magnitude of
429 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
430 magnitude is equal to or greater than one, then it returns the largest
431 whole number that does not exceed its magnitude. The sign is the same
432 as the sign of @var{X}.
434 @item @emph{Example}:
441 print *, aint(x4), dint(x8)
443 end program test_aint
446 @item @emph{Specific names}:
447 @multitable @columnfractions .24 .24 .24 .24
448 @item Name @tab Argument @tab Return type @tab Option
449 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
455 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
456 @findex @code{ALL} intrinsic
460 @item @emph{Description}:
461 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
462 in the array along dimension @var{DIM}.
468 transformational function
471 @code{L = ALL(MASK)} @*
472 @code{L = ALL(MASK, DIM)}
474 @item @emph{Arguments}:
475 @multitable @columnfractions .15 .80
476 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
477 it shall not be scalar.
478 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
479 with a value that lies between one and the rank of @var{MASK}.
482 @item @emph{Return value}:
483 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
484 the kind type parameter is the same as the kind type parameter of
485 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
486 an array with the rank of @var{MASK} minus 1. The shape is determined from
487 the shape of @var{MASK} where the @var{DIM} dimension is elided.
491 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
492 It also is true if @var{MASK} has zero size; otherwise, it is false.
494 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
495 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
496 is determined by applying @code{ALL} to the array sections.
499 @item @emph{Example}:
503 l = all((/.true., .true., .true./))
508 integer a(2,3), b(2,3)
512 print *, all(a .eq. b, 1)
513 print *, all(a .eq. b, 2)
514 end subroutine section
521 @section @code{ALLOCATED} --- Status of an allocatable entity
522 @findex @code{ALLOCATED} intrinsic
523 @cindex allocation status
526 @item @emph{Description}:
527 @code{ALLOCATED(X)} checks the status of wether @var{X} is allocated.
536 @code{L = ALLOCATED(X)}
538 @item @emph{Arguments}:
539 @multitable @columnfractions .15 .80
540 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
543 @item @emph{Return value}:
544 The return value is a scalar @code{LOGICAL} with the default logical
545 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
546 is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.}
548 @item @emph{Example}:
550 program test_allocated
552 real(4), allocatable :: x(:)
553 if (allocated(x) .eqv. .false.) allocate(x(i)
554 end program test_allocated
560 @section @code{ANINT} --- Imaginary part of complex number
561 @findex @code{ANINT} intrinsic
562 @findex @code{DNINT} intrinsic
566 @item @emph{Description}:
567 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
576 @code{X = ANINT(X)} @*
577 @code{X = ANINT(X, KIND)}
579 @item @emph{Arguments}:
580 @multitable @columnfractions .15 .80
581 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
582 @item @var{KIND} @tab (Optional) @var{KIND} shall be a scalar integer
583 initialization expression.
586 @item @emph{Return value}:
587 The return value is of type real with the kind type parameter of the
588 argument if the optional @var{KIND} is absence; otherwise, the kind
589 type parameter will be given by @var{KIND}. If @var{X} is greater than
590 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
591 less than or equal to zero, then return @code{AINT(X-0.5)}.
593 @item @emph{Example}:
600 print *, anint(x4), dnint(x8)
602 end program test_anint
605 @item @emph{Specific names}:
606 @multitable @columnfractions .24 .24 .24 .24
607 @item Name @tab Argument @tab Return type @tab Option
608 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
614 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
615 @findex @code{ANY} intrinsic
619 @item @emph{Description}:
620 @code{ANY(MASK [, DIM])} determines if any of the values is true in @var{MASK}
621 in the array along dimension @var{DIM}.
627 transformational function
630 @code{L = ANY(MASK)} @*
631 @code{L = ANY(MASK, DIM)}
633 @item @emph{Arguments}:
634 @multitable @columnfractions .15 .80
635 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
636 it shall not be scalar.
637 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
638 with a value that lies between one and the rank of @var{MASK}.
641 @item @emph{Return value}:
642 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
643 the kind type parameter is the same as the kind type parameter of
644 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
645 an array with the rank of @var{MASK} minus 1. The shape is determined from
646 the shape of @var{MASK} where the @var{DIM} dimension is elided.
650 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
651 otherwise, it is false. It also is false if @var{MASK} has zero size.
653 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
654 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
655 is determined by applying @code{ANY} to the array sections.
658 @item @emph{Example}:
662 l = any((/.true., .true., .true./))
667 integer a(2,3), b(2,3)
671 print *, any(a .eq. b, 1)
672 print *, any(a .eq. b, 2)
673 end subroutine section
680 @section @code{ASIN} --- Arcsine function
681 @findex @code{ASIN} intrinsic
682 @findex @code{DASIN} intrinsic
686 @item @emph{Description}:
687 @code{ASIN(X)} computes the arcsine of its @var{X}.
698 @item @emph{Arguments}:
699 @multitable @columnfractions .15 .80
700 @item @var{X} @tab The type shall be an @code{REAL(*)}, and a magnitude that is
704 @item @emph{Return value}:
705 The return value is of type @code{REAL(*)} and it lies in the
706 range @math{ \pi / 2 \leq \arccos (x) \leq \pi / 2}. The kind type
707 parameter is the same as @var{X}.
709 @item @emph{Example}:
712 real(8) :: x = 0.866_8
714 end program test_asin
717 @item @emph{Specific names}:
718 @multitable @columnfractions .24 .24 .24 .24
719 @item Name @tab Argument @tab Return type @tab Option
720 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
728 @comment gen associated
754 @comment gen bit_size
764 @comment gen command_argument_count
779 @comment sub cpu_time
783 @comment sub date_and_time
796 @comment gen dot_product
824 @comment gen exponent
832 @comment gen fraction
850 @comment sub get_command
852 @comment sub get_command_argument
854 @comment sub get_environment_variable
894 @comment gen len_trim
925 @comment gen maxexponent
940 @comment gen minexponent
965 @comment gen precision
976 @comment sub random_number
978 @comment sub random_seed
990 @comment gen rrspacing
999 @comment gen selected_int_kind
1001 @comment gen selected_real_kind
1003 @comment gen set_exponent
1021 @comment gen spacing
1028 @comment zsqrt,cdsqrt
1040 @comment sub system_clock
1050 @comment gen transfer
1052 @comment gen transpose