gcc/fortran/intrinsic.texi

   1 @ignore
   2 Copyright (C) 2005
   3 Free Software Foundation, Inc.
   4 This is part of the GFORTRAN manual.
   5 For copying conditions, see the file gfortran.texi.
   6
   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.
  14
  15
  16 Some basic guidelines for editing this document:
  17
  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.
  23
  24
  25 @end ignore
  26
  27 @node Intrinsic Procedures
  28 @chapter Intrinsic Procedures
  29 @cindex Intrinsic Procedures
  30
  31 This portion of the document is incomplete and undergoing massive expansion
  32 and editing.  All contributions and corrections are strongly encouraged.
  33
  34 @menu
  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,      Arc cosine 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
  49 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
  50 * @code{ATAN}:          ATAN,      Arctangent function
  51 * @code{ATAN2}:         ATAN2,     Arctangent function
  52 * @code{BESJ0}:         BESJ0,     Bessel function of the first kind of order 0
  53 * @code{BESJ1}:         BESJ1,     Bessel function of the first kind of order 1
  54 * @code{BESJN}:         BESJN,     Bessel function of the first kind
  55 * @code{BESY0}:         BESY0,     Bessel function of the second kind of order 0
  56 * @code{BESY1}:         BESY1,     Bessel function of the second kind of order 1
  57 * @code{BESYN}:         BESYN,     Bessel function of the second kind
  58 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  59 * @code{BTEST}:         BTEST,     Bit test function
  60 * @code{CEILING}:       CEILING,   Integer ceiling function
  61 * @code{CHAR}:          CHAR,      Character conversion function
  62 * @code{CMPLX}:         CMPLX,     Complex conversion function
  63 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT,  Command line argument count
  64 * @code{CONJG}:         CONJG,     Complex conjugate function
  65 * @code{COS}:           COS,       Cosine function
  66 * @code{COSH}:          COSH,      Hyperbolic cosine function
  67 * @code{COUNT}:         COUNT,     Count occurrences of .TRUE. in an array
  68 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  69 * @code{CSHIFT}:        CSHIFT,    Circular array shift function
  70 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
  71 * @code{DBLE}:          DBLE,      Double precision conversion function
  72 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
  73 * @code{DFLOAT}:        DFLOAT,    Double precision conversion function
  74 * @code{DIGITS}:        DIGITS,    Significant digits function
  75 * @code{DIM}:           DIM,       Dim function
  76 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
  77 * @code{DPROD}:         DPROD,     Double product function
  78 * @code{DREAL}:         DREAL,     Double real part function
  79 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
  80 * @code{EOSHIFT}:       EOSHIFT,   End-off shift function
  81 * @code{EPSILON}:       EPSILON,   Epsilon function
  82 * @code{ERF}:           ERF,       Error function
  83 * @code{ERFC}:          ERFC,      Complementary error function
  84 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
  85 * @code{EXIT}:          EXIT,      Exit the program with status.
  86 * @code{EXP}:           EXP,       Exponential function
  87 * @code{EXPONENT}:      EXPONENT,  Exponent function
  88 * @code{FLOOR}:         FLOOR,     Integer floor function
  89 * @code{FNUM}:          FNUM,      File number function
  90 * @code{LOG}:           LOG,       Logarithm function
  91 * @code{LOG10}:         LOG10,     Base 10 logarithm function
  92 * @code{REAL}:          REAL,      Convert to real type
  93 * @code{SQRT}:          SQRT,      Square-root function
  94 * @code{SIN}:           SIN,       Sine function
  95 * @code{SINH}:          SINH,      Hyperbolic sine function
  96 * @code{TAN}:           TAN,       Tangent function
  97 * @code{TANH}:          TANH,      Hyperbolic tangent function
  98 @end menu
  99
 100 @node Introduction
 101 @section Introduction to intrinsic procedures
 102
 103 Gfortran provides a rich set of intrinsic procedures that includes all
 104 the intrinsic procedures required by the Fortran 95 standard, a set of
 105 intrinsic procedures for backwards compatibility with Gnu Fortran 77
 106 (i.e., @command{g77}), and a small selection of intrinsic procedures
 107 from the Fortran 2003 standard.  Any description here, which conflicts with a
 108 description in either the Fortran 95 standard or the Fortran 2003 standard,
 109 is unintentional and the standard(s) should be considered authoritative.
 110
 111 The enumeration of the @code{KIND} type parameter is processor defined in
 112 the Fortran 95 standard.  Gfortran defines the default integer type and
 113 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 114 respectively.  The standard mandates that both data types shall have
 115 another kind, which have more precision.  On typical target architectures
 116 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 117 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 118 In the description of generic intrinsic procedures, the kind type parameter
 119 will be specified by @code{KIND=*}, and in the description of specific
 120 names for an intrinsic procedure the kind type parameter will be explicitly
 121 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 122 brevity the optional @code{KIND=} syntax will be omitted.
 123
 124 Many of the intrinsics procedures take one or more optional arguments.
 125 This document follows the convention used in the Fortran 95 standard,
 126 and denotes such arguments by square brackets.
 127
 128 @command{Gfortran} offers the @option{-std=f95} and @option{-std=gnu} options,
 129 which can be used to restrict the set of intrinsic procedures to a
 130 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 131 option, and so all intrinsic procedures described here are accepted.  There
 132 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 133 implemented both a function and a subroutine.  Both classes
 134 have been implemented in @command{gfortran} for backwards compatibility
 135 with @command{g77}.  It is noted here that these functions and subroutines
 136 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 137 the applicable option(s) is noted.
 138
 139
 140
 141 @node ABORT
 142 @section @code{ABORT} --- Abort the program
 143 @findex @code{ABORT}
 144 @cindex abort
 145
 146 @table @asis
 147 @item @emph{Description}:
 148 @code{ABORT} causes immediate termination of the program.  On operating
 149 systems that support a core dump, @code{ABORT} will produce a core dump,
 150 which is suitable for debugging purposes.
 151
 152 @item @emph{Option}:
 153 gnu
 154
 155 @item @emph{Class}:
 156 non-elemental subroutine
 157
 158 @item @emph{Syntax}:
 159 @code{CALL ABORT}
 160
 161 @item @emph{Return value}:
 162 Does not return.
 163
 164 @item @emph{Example}:
 165 @smallexample
 166 program test_abort
 167   integer :: i = 1, j = 2
 168   if (i /= j) call abort
 169 end program test_abort
 170 @end smallexample
 171 @end table
 172
 173
 174
 175 @node ABS
 176 @section @code{ABS} --- Absolute value
 177 @findex @code{ABS} intrinsic
 178 @findex @code{CABS} intrinsic
 179 @findex @code{DABS} intrinsic
 180 @findex @code{IABS} intrinsic
 181 @findex @code{ZABS} intrinsic
 182 @findex @code{CDABS} intrinsic
 183 @cindex absolute value
 184
 185 @table @asis
 186 @item @emph{Description}:
 187 @code{ABS(X)} computes the absolute value of @code{X}.
 188
 189 @item @emph{Option}:
 190 f95, gnu
 191
 192 @item @emph{Class}:
 193 elemental function
 194
 195 @item @emph{Syntax}:
 196 @code{X = ABS(X)}
 197
 198 @item @emph{Arguments}:
 199 @multitable @columnfractions .15 .80
 200 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
 201 @code{REAL(*)}, or @code{COMPLEX(*)}.
 202 @end multitable
 203
 204 @item @emph{Return value}:
 205 The return value is of the same type and
 206 kind as the argument except the return value is @code{REAL(*)} for a
 207 @code{COMPLEX(*)} argument.
 208
 209 @item @emph{Example}:
 210 @smallexample
 211 program test_abs
 212   integer :: i = -1
 213   real :: x = -1.e0
 214   complex :: z = (-1.e0,0.e0)
 215   i = abs(i)
 216   x = abs(x)
 217   x = abs(z)
 218 end program test_abs
 219 @end smallexample
 220
 221 @item @emph{Specific names}:
 222 @multitable @columnfractions .24 .24 .24 .24
 223 @item Name            @tab Argument            @tab Return type       @tab Option
 224 @item @code{CABS(Z)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab f95, gnu
 225 @item @code{DABS(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab f95, gnu
 226 @item @code{IABS(I)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab f95, gnu
 227 @item @code{ZABS(Z)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
 228 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
 229 @end multitable
 230 @end table
 231
 232
 233
 234 @node ACHAR
 235 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
 236 @findex @code{ACHAR} intrinsic
 237 @cindex @acronym{ASCII} collating sequence
 238
 239 @table @asis
 240 @item @emph{Description}:
 241 @code{ACHAR(I)} returns the character located at position @code{I}
 242 in the @acronym{ASCII} collating sequence.
 243
 244 @item @emph{Option}:
 245 f95, gnu
 246
 247 @item @emph{Class}:
 248 elemental function
 249
 250 @item @emph{Syntax}:
 251 @code{C = ACHAR(I)}
 252
 253 @item @emph{Arguments}:
 254 @multitable @columnfractions .15 .80
 255 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
 256 @end multitable
 257
 258 @item @emph{Return value}:
 259 The return value is of type @code{CHARACTER} with a length of one.  The
 260 kind type parameter is the same as  @code{KIND('A')}.
 261
 262 @item @emph{Example}:
 263 @smallexample
 264 program test_achar
 265   character c
 266   c = achar(32)
 267 end program test_achar
 268 @end smallexample
 269 @end table
 270
 271
 272
 273 @node ACOS
 274 @section @code{ACOS} --- Arc cosine function
 275 @findex @code{ACOS} intrinsic
 276 @findex @code{DACOS} intrinsic
 277 @cindex arc cosine
 278
 279 @table @asis
 280 @item @emph{Description}:
 281 @code{ACOS(X)} computes the arc cosine of @var{X}.
 282
 283 @item @emph{Option}:
 284 f95, gnu
 285
 286 @item @emph{Class}:
 287 elemental function
 288
 289 @item @emph{Syntax}:
 290 @code{X = ACOS(X)}
 291
 292 @item @emph{Arguments}:
 293 @multitable @columnfractions .15 .80
 294 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
 295 less than one.
 296 @end multitable
 297
 298 @item @emph{Return value}:
 299 The return value is of type @code{REAL(*)} and it lies in the
 300 range @math{ 0 \leq \arccos (x) \leq \pi}.  The kind type
 301 parameter is the same as @var{X}.
 302
 303 @item @emph{Example}:
 304 @smallexample
 305 program test_acos
 306   real(8) :: x = 0.866_8
 307   x = achar(x)
 308 end program test_acos
 309 @end smallexample
 310
 311 @item @emph{Specific names}:
 312 @multitable @columnfractions .24 .24 .24 .24
 313 @item Name            @tab Argument          @tab Return type       @tab Option
 314 @item @code{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
 315 @end multitable
 316 @end table
 317
 318
 319
 320 @node ADJUSTL
 321 @section @code{ADJUSTL} --- Left adjust a string
 322 @findex @code{ADJUSTL} intrinsic
 323 @cindex adjust string
 324
 325 @table @asis
 326 @item @emph{Description}:
 327 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
 328 Spaces are inserted at the end of the string as needed.
 329
 330 @item @emph{Option}:
 331 f95, gnu
 332
 333 @item @emph{Class}:
 334 elemental function
 335
 336 @item @emph{Syntax}:
 337 @code{STR = ADJUSTL(STR)}
 338
 339 @item @emph{Arguments}:
 340 @multitable @columnfractions .15 .80
 341 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 342 @end multitable
 343
 344 @item @emph{Return value}:
 345 The return value is of type @code{CHARACTER} where leading spaces
 346 are removed and the same number of spaces are inserted on the end
 347 of @var{STR}.
 348
 349 @item @emph{Example}:
 350 @smallexample
 351 program test_adjustl
 352   character(len=20) :: str = '   gfortran'
 353   str = adjustl(str)
 354   print *, str
 355 end program test_adjustl
 356 @end smallexample
 357 @end table
 358
 359
 360
 361 @node ADJUSTR
 362 @section @code{ADJUSTR} --- Right adjust a string
 363 @findex @code{ADJUSTR} intrinsic
 364 @cindex adjust string
 365
 366 @table @asis
 367 @item @emph{Description}:
 368 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
 369 Spaces are inserted at the start of the string as needed.
 370
 371 @item @emph{Option}:
 372 f95, gnu
 373
 374 @item @emph{Class}:
 375 elemental function
 376
 377 @item @emph{Syntax}:
 378 @code{STR = ADJUSTR(STR)}
 379
 380 @item @emph{Arguments}:
 381 @multitable @columnfractions .15 .80
 382 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 383 @end multitable
 384
 385 @item @emph{Return value}:
 386 The return value is of type @code{CHARACTER} where trailing spaces
 387 are removed and the same number of spaces are inserted at the start
 388 of @var{STR}.
 389
 390 @item @emph{Example}:
 391 @smallexample
 392 program test_adjustr
 393   character(len=20) :: str = 'gfortran'
 394   str = adjustr(str)
 395   print *, str
 396 end program test_adjustr
 397 @end smallexample
 398 @end table
 399
 400
 401
 402 @node AIMAG
 403 @section @code{AIMAG} --- Imaginary part of complex number
 404 @findex @code{AIMAG} intrinsic
 405 @findex @code{DIMAG} intrinsic
 406 @findex @code{IMAG} intrinsic
 407 @findex @code{IMAGPART} intrinsic
 408 @cindex Imaginary part
 409
 410 @table @asis
 411 @item @emph{Description}:
 412 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
 413 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
 414 for compatibility with @command{g77}, and their use in new code is
 415 strongly discouraged.
 416
 417 @item @emph{Option}:
 418 f95, gnu
 419
 420 @item @emph{Class}:
 421 elemental function
 422
 423 @item @emph{Syntax}:
 424 @code{X = AIMAG(Z)}
 425
 426 @item @emph{Arguments}:
 427 @multitable @columnfractions .15 .80
 428 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
 429 @end multitable
 430
 431 @item @emph{Return value}:
 432 The return value is of type real with the
 433 kind type parameter of the argument.
 434
 435 @item @emph{Example}:
 436 @smallexample
 437 program test_aimag
 438   complex(4) z4
 439   complex(8) z8
 440   z4 = cmplx(1.e0_4, 0.e0_4)
 441   z8 = cmplx(0.e0_8, 1.e0_8)
 442   print *, aimag(z4), dimag(z8)
 443 end program test_aimag
 444 @end smallexample
 445
 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{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}    @tab f95, gnu
 450 @item @code{IMAG(Z)}  @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)}    @tab gnu
 451 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab gnu
 452 @end multitable
 453 @end table
 454
 455
 456
 457 @node AINT
 458 @section @code{AINT} --- Imaginary part of complex number
 459 @findex @code{AINT} intrinsic
 460 @findex @code{DINT} intrinsic
 461 @cindex whole number
 462
 463 @table @asis
 464 @item @emph{Description}:
 465 @code{AINT(X [, KIND])} truncates its argument to a whole number.
 466
 467 @item @emph{Option}:
 468 f95, gnu
 469
 470 @item @emph{Class}:
 471 elemental function
 472
 473 @item @emph{Syntax}:
 474 @code{X = AINT(X)}
 475 @code{X = AINT(X, KIND)}
 476
 477 @item @emph{Arguments}:
 478 @multitable @columnfractions .15 .80
 479 @item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
 480 @item @var{KIND} @tab (Optional) @var{KIND} shall be a scalar integer
 481 initialization expression.
 482 @end multitable
 483
 484 @item @emph{Return value}:
 485 The return value is of type real with the kind type parameter of the
 486 argument if the optional @var{KIND} is absent; otherwise, the kind
 487 type parameter will be given by @var{KIND}.  If the magnitude of
 488 @var{X} is less than one, then @code{AINT(X)} returns zero.  If the
 489 magnitude is equal to or greater than one, then it returns the largest
 490 whole number that does not exceed its magnitude.  The sign is the same
 491 as the sign of @var{X}.
 492
 493 @item @emph{Example}:
 494 @smallexample
 495 program test_aint
 496   real(4) x4
 497   real(8) x8
 498   x4 = 1.234E0_4
 499   x8 = 4.321_8
 500   print *, aint(x4), dint(x8)
 501   x8 = aint(x4,8)
 502 end program test_aint
 503 @end smallexample
 504
 505 @item @emph{Specific names}:
 506 @multitable @columnfractions .24 .24 .24 .24
 507 @item Name           @tab Argument         @tab Return type      @tab Option
 508 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab f95, gnu
 509 @end multitable
 510 @end table
 511
 512
 513
 514 @node ALL
 515 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
 516 @findex @code{ALL} intrinsic
 517 @cindex true values
 518
 519 @table @asis
 520 @item @emph{Description}:
 521 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
 522 in the array along dimension @var{DIM}.
 523
 524 @item @emph{Option}:
 525 f95, gnu
 526
 527 @item @emph{Class}:
 528 transformational function
 529
 530 @item @emph{Syntax}:
 531 @code{L = ALL(MASK)}
 532 @code{L = ALL(MASK, DIM)}
 533
 534 @item @emph{Arguments}:
 535 @multitable @columnfractions .15 .80
 536 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
 537 it shall not be scalar.
 538 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 539 with a value that lies between one and the rank of @var{MASK}.
 540 @end multitable
 541
 542 @item @emph{Return value}:
 543 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
 544 the kind type parameter is the same as the kind type parameter of
 545 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
 546 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 547 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 548
 549 @table @asis
 550 @item (A)
 551 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
 552 It also is true if @var{MASK} has zero size; otherwise, it is false.
 553 @item (B)
 554 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
 555 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
 556 is determined by applying @code{ALL} to the array sections.
 557 @end table
 558
 559 @item @emph{Example}:
 560 @smallexample
 561 program test_all
 562   logical l
 563   l = all((/.true., .true., .true./))
 564   print *, l
 565   call section
 566   contains
 567     subroutine section
 568       integer a(2,3), b(2,3)
 569       a = 1
 570       b = 1
 571       b(2,2) = 2
 572       print *, all(a .eq. b, 1)
 573       print *, all(a .eq. b, 2)
 574     end subroutine section
 575 end program test_all
 576 @end smallexample
 577 @end table
 578
 579
 580
 581 @node ALLOCATED
 582 @section @code{ALLOCATED} --- Status of an allocatable entity
 583 @findex @code{ALLOCATED} intrinsic
 584 @cindex allocation status
 585
 586 @table @asis
 587 @item @emph{Description}:
 588 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
 589
 590 @item @emph{Option}:
 591 f95, gnu
 592
 593 @item @emph{Class}:
 594 inquiry function
 595
 596 @item @emph{Syntax}:
 597 @code{L = ALLOCATED(X)}
 598
 599 @item @emph{Arguments}:
 600 @multitable @columnfractions .15 .80
 601 @item @var{X}    @tab The argument shall be an @code{ALLOCATABLE} array.
 602 @end multitable
 603
 604 @item @emph{Return value}:
 605 The return value is a scalar @code{LOGICAL} with the default logical
 606 kind type parameter.  If @var{X} is allocated, @code{ALLOCATED(X)}
 607 is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.}
 608
 609 @item @emph{Example}:
 610 @smallexample
 611 program test_allocated
 612   integer :: i = 4
 613   real(4), allocatable :: x(:)
 614   if (allocated(x) .eqv. .false.) allocate(x(i)
 615 end program test_allocated
 616 @end smallexample
 617 @end table
 618
 619
 620
 621 @node ANINT
 622 @section @code{ANINT} --- Imaginary part of complex number
 623 @findex @code{ANINT} intrinsic
 624 @findex @code{DNINT} intrinsic
 625 @cindex whole number
 626
 627 @table @asis
 628 @item @emph{Description}:
 629 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
 630
 631 @item @emph{Option}:
 632 f95, gnu
 633
 634 @item @emph{Class}:
 635 elemental function
 636
 637 @item @emph{Syntax}:
 638 @code{X = ANINT(X)}
 639 @code{X = ANINT(X, KIND)}
 640
 641 @item @emph{Arguments}:
 642 @multitable @columnfractions .15 .80
 643 @item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
 644 @item @var{KIND} @tab (Optional) @var{KIND} shall be a scalar integer
 645 initialization expression.
 646 @end multitable
 647
 648 @item @emph{Return value}:
 649 The return value is of type real with the kind type parameter of the
 650 argument if the optional @var{KIND} is absent; otherwise, the kind
 651 type parameter will be given by @var{KIND}.  If @var{X} is greater than
 652 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}.  If @var{X} is
 653 less than or equal to zero, then return @code{AINT(X-0.5)}.
 654
 655 @item @emph{Example}:
 656 @smallexample
 657 program test_anint
 658   real(4) x4
 659   real(8) x8
 660   x4 = 1.234E0_4
 661   x8 = 4.321_8
 662   print *, anint(x4), dnint(x8)
 663   x8 = anint(x4,8)
 664 end program test_anint
 665 @end smallexample
 666
 667 @item @emph{Specific names}:
 668 @multitable @columnfractions .24 .24 .24 .24
 669 @item Name            @tab Argument         @tab Return type      @tab Option
 670 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab f95, gnu
 671 @end multitable
 672 @end table
 673
 674
 675
 676 @node ANY
 677 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
 678 @findex @code{ANY} intrinsic
 679 @cindex true values
 680
 681 @table @asis
 682 @item @emph{Description}:
 683 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
 684 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
 685
 686 @item @emph{Option}:
 687 f95, gnu
 688
 689 @item @emph{Class}:
 690 transformational function
 691
 692 @item @emph{Syntax}:
 693 @code{L = ANY(MASK)}
 694 @code{L = ANY(MASK, DIM)}
 695
 696 @item @emph{Arguments}:
 697 @multitable @columnfractions .15 .80
 698 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
 699 it shall not be scalar.
 700 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 701 with a value that lies between one and the rank of @var{MASK}.
 702 @end multitable
 703
 704 @item @emph{Return value}:
 705 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
 706 the kind type parameter is the same as the kind type parameter of
 707 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
 708 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 709 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 710
 711 @table @asis
 712 @item (A)
 713 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
 714 otherwise, it is false.  It also is false if @var{MASK} has zero size.
 715 @item (B)
 716 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
 717 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
 718 is determined by applying @code{ANY} to the array sections.
 719 @end table
 720
 721 @item @emph{Example}:
 722 @smallexample
 723 program test_any
 724   logical l
 725   l = any((/.true., .true., .true./))
 726   print *, l
 727   call section
 728   contains
 729     subroutine section
 730       integer a(2,3), b(2,3)
 731       a = 1
 732       b = 1
 733       b(2,2) = 2
 734       print *, any(a .eq. b, 1)
 735       print *, any(a .eq. b, 2)
 736     end subroutine section
 737 end program test_any
 738 @end smallexample
 739 @end table
 740
 741
 742
 743 @node ASIN
 744 @section @code{ASIN} --- Arcsine function
 745 @findex @code{ASIN} intrinsic
 746 @findex @code{DASIN} intrinsic
 747 @cindex arcsine
 748
 749 @table @asis
 750 @item @emph{Description}:
 751 @code{ASIN(X)} computes the arcsine of its @var{X}.
 752
 753 @item @emph{Option}:
 754 f95, gnu
 755
 756 @item @emph{Class}:
 757 elemental function
 758
 759 @item @emph{Syntax}:
 760 @code{X = ASIN(X)}
 761
 762 @item @emph{Arguments}:
 763 @multitable @columnfractions .15 .80
 764 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
 765 less than one.
 766 @end multitable
 767
 768 @item @emph{Return value}:
 769 The return value is of type @code{REAL(*)} and it lies in the
 770 range @math{-\pi / 2 \leq \arccos (x) \leq \pi / 2}.  The kind type
 771 parameter is the same as @var{X}.
 772
 773 @item @emph{Example}:
 774 @smallexample
 775 program test_asin
 776   real(8) :: x = 0.866_8
 777   x = asin(x)
 778 end program test_asin
 779 @end smallexample
 780
 781 @item @emph{Specific names}:
 782 @multitable @columnfractions .24 .24 .24 .24
 783 @item Name            @tab Argument          @tab Return type       @tab Option
 784 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
 785 @end multitable
 786 @end table
 787
 788
 789
 790 @node ASSOCIATED
 791 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
 792 @findex @code{ASSOCIATED} intrinsic
 793 @cindex pointer status
 794
 795 @table @asis
 796 @item @emph{Description}:
 797 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
 798 or if @var{PTR} is associated with the target @var{TGT}.
 799
 800 @item @emph{Option}:
 801 f95, gnu
 802
 803 @item @emph{Class}:
 804 inquiry function
 805
 806 @item @emph{Syntax}:
 807 @code{L = ASSOCIATED(PTR)}
 808 @code{L = ASSOCIATED(PTR [, TGT])}
 809
 810 @item @emph{Arguments}:
 811 @multitable @columnfractions .15 .80
 812 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
 813 it can be of any type.
 814 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
 815 a @code{TARGET}.  It must have the same type, kind type parameter, and
 816 array rank as @var{PTR}.
 817 @end multitable
 818 The status of neither @var{PTR} nor @var{TGT} can be undefined.
 819
 820 @item @emph{Return value}:
 821 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
 822 There are several cases:
 823 @table @asis
 824 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
 825 is true if @var{PTR} is associated with a target; otherwise, it returns false.
 826 @item (B) If @var{TGT} is present and a scalar target, the result is true if
 827 @var{TGT}
 828 is not a 0 sized storage sequence and the target associated with @var{PTR}
 829 occupies the same storage units.  If @var{PTR} is disassociated, then the
 830 result is false.
 831 @item (C) If @var{TGT} is present and an array target, the result is true if
 832 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
 833 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
 834 @var{PTR} occupy the same storage units in array element order.
 835 As in case(B), the result is false, if @var{PTR} is disassociated.
 836 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
 837 target associated with @var{PTR} and the target associated with @var{TGT}
 838 are not 0 sized storage sequences and occupy the same storage units.
 839 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
 840 @item (E) If @var{TGT} is present and an array pointer, the result is true if
 841 target associated with @var{PTR} and the target associated with @var{TGT}
 842 have the same shape, are not 0 sized arrays, are arrays whose elements are
 843 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
 844 storage units in array element order.
 845 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
 846 @end table
 847
 848 @item @emph{Example}:
 849 @smallexample
 850 program test_associated
 851    implicit none
 852    real, target  :: tgt(2) = (/1., 2./)
 853    real, pointer :: ptr(:)
 854    ptr => tgt
 855    if (associated(ptr)     .eqv. .false.) call abort
 856    if (associated(ptr,tgt) .eqv. .false.) call abort
 857 end program test_associated
 858 @end smallexample
 859 @end table
 860
 861
 862
 863 @node ATAN
 864 @section @code{ATAN} --- Arctangent function
 865 @findex @code{ATAN} intrinsic
 866 @findex @code{DATAN} intrinsic
 867 @cindex arctangent
 868
 869 @table @asis
 870 @item @emph{Description}:
 871 @code{ATAN(X)} computes the arctangent of @var{X}.
 872
 873 @item @emph{Option}:
 874 f95, gnu
 875
 876 @item @emph{Class}:
 877 elemental function
 878
 879 @item @emph{Syntax}:
 880 @code{X = ATAN(X)}
 881
 882 @item @emph{Arguments}:
 883 @multitable @columnfractions .15 .80
 884 @item @var{X} @tab The type shall be @code{REAL(*)}.
 885 @end multitable
 886
 887 @item @emph{Return value}:
 888 The return value is of type @code{REAL(*)} and it lies in the
 889 range @math{ - \pi / 2 \leq \arcsin (x) \leq \pi / 2}.
 890
 891 @item @emph{Example}:
 892 @smallexample
 893 program test_atan
 894   real(8) :: x = 2.866_8
 895   x = atan(x)
 896 end program test_atan
 897 @end smallexample
 898
 899 @item @emph{Specific names}:
 900 @multitable @columnfractions .24 .24 .24 .24
 901 @item Name            @tab Argument          @tab Return type       @tab Option
 902 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
 903 @end multitable
 904 @end table
 905
 906
 907
 908 @node ATAN2
 909 @section @code{ATAN2} --- Arctangent function
 910 @findex @code{ATAN2} intrinsic
 911 @findex @code{DATAN2} intrinsic
 912 @cindex arctangent
 913
 914 @table @asis
 915 @item @emph{Description}:
 916 @code{ATAN2(Y,X)} computes the arctangent of the complex number @math{X + i Y}.
 917
 918 @item @emph{Option}:
 919 f95, gnu
 920
 921 @item @emph{Class}:
 922 elemental function
 923
 924 @item @emph{Syntax}:
 925 @code{X = ATAN2(Y,X)}
 926
 927 @item @emph{Arguments}:
 928 @multitable @columnfractions .15 .80
 929 @item @var{Y} @tab The type shall be @code{REAL(*)}.
 930 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
 931 If @var{Y} is zero, then @var{X} must be nonzero.
 932 @end multitable
 933
 934 @item @emph{Return value}:
 935 The return value has the same type and kind type parameter as @var{Y}.
 936 It is the principle value of the complex number @math{X + i Y}.  If
 937 @var{X} is nonzero, then it lies in the range @math{-\pi \le \arccos (x) \leq \pi}.
 938 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
 939 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
 940 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
 941 is @math{\pi/2}.
 942
 943 @item @emph{Example}:
 944 @smallexample
 945 program test_atan2
 946   real(4) :: x = 1.e0_4, y = 0.5e0_4
 947   x = atan2(y,x)
 948 end program test_atan2
 949 @end smallexample
 950
 951 @item @emph{Specific names}:
 952 @multitable @columnfractions .24 .24 .24 .24
 953 @item Name            @tab Argument          @tab Return type    @tab Option
 954 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
 955 @end multitable
 956 @end table
 957
 958
 959
 960 @node BESJ0
 961 @section @code{BESJ0} --- Bessel function of the first kind of order 0
 962 @findex @code{BESJ0} intrinsic
 963 @findex @code{DBESJ0} intrinsic
 964 @cindex Bessel
 965
 966 @table @asis
 967 @item @emph{Description}:
 968 @code{BESJ0(X)} computes the Bessel function of the first kind of order 0
 969 of @var{X}.
 970
 971 @item @emph{Option}:
 972 gnu
 973
 974 @item @emph{Class}:
 975 elemental function
 976
 977 @item @emph{Syntax}:
 978 @code{X = BESJ0(X)}
 979
 980 @item @emph{Arguments}:
 981 @multitable @columnfractions .15 .80
 982 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
 983 @end multitable
 984
 985 @item @emph{Return value}:
 986 The return value is of type @code{REAL(*)} and it lies in the
 987 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
 988
 989 @item @emph{Example}:
 990 @smallexample
 991 program test_besj0
 992   real(8) :: x = 0.0_8
 993   x = besj0(x)
 994 end program test_besj0
 995 @end smallexample
 996
 997 @item @emph{Specific names}:
 998 @multitable @columnfractions .24 .24 .24 .24
 999 @item Name            @tab Argument          @tab Return type       @tab Option
1000 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab gnu
1001 @end multitable
1002 @end table
1003
1004
1005
1006 @node BESJ1
1007 @section @code{BESJ1} --- Bessel function of the first kind of order 1
1008 @findex @code{BESJ1} intrinsic
1009 @findex @code{DBESJ1} intrinsic
1010 @cindex Bessel
1011
1012 @table @asis
1013 @item @emph{Description}:
1014 @code{BESJ1(X)} computes the Bessel function of the first kind of order 1
1015 of @var{X}.
1016
1017 @item @emph{Option}:
1018 gnu
1019
1020 @item @emph{Class}:
1021 elemental function
1022
1023 @item @emph{Syntax}:
1024 @code{X = BESJ1(X)}
1025
1026 @item @emph{Arguments}:
1027 @multitable @columnfractions .15 .80
1028 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1029 @end multitable
1030
1031 @item @emph{Return value}:
1032 The return value is of type @code{REAL(*)} and it lies in the
1033 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1034
1035 @item @emph{Example}:
1036 @smallexample
1037 program test_besj1
1038   real(8) :: x = 1.0_8
1039   x = besj1(x)
1040 end program test_besj1
1041 @end smallexample
1042
1043 @item @emph{Specific names}:
1044 @multitable @columnfractions .24 .24 .24 .24
1045 @item Name            @tab Argument          @tab Return type       @tab Option
1046 @item @code{DBESJ1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab gnu
1047 @end multitable
1048 @end table
1049
1050
1051
1052 @node BESJN
1053 @section @code{BESJN} --- Bessel function of the first kind
1054 @findex @code{BESJN} intrinsic
1055 @findex @code{DBESJN} intrinsic
1056 @cindex Bessel
1057
1058 @table @asis
1059 @item @emph{Description}:
1060 @code{BESJN(N, X)} computes the Bessel function of the first kind of order
1061 @var{N} of @var{X}.
1062
1063 @item @emph{Option}:
1064 gnu
1065
1066 @item @emph{Class}:
1067 elemental function
1068
1069 @item @emph{Syntax}:
1070 @code{Y = BESJN(N, X)}
1071
1072 @item @emph{Arguments}:
1073 @multitable @columnfractions .15 .80
1074 @item @var{N} @tab The type shall be @code{INTEGER(*)}, and it shall be scalar.
1075 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1076 @end multitable
1077
1078 @item @emph{Return value}:
1079 The return value is a scalar of type @code{REAL(*)}.
1080
1081 @item @emph{Example}:
1082 @smallexample
1083 program test_besjn
1084   real(8) :: x = 1.0_8
1085   x = besjn(5,x)
1086 end program test_besjn
1087 @end smallexample
1088
1089 @item @emph{Specific names}:
1090 @multitable @columnfractions .24 .24 .24 .24
1091 @item Name             @tab Argument            @tab Return type       @tab Option
1092 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)}    @tab gnu
1093 @item                  @tab @code{REAL(8) X}    @tab                   @tab
1094 @end multitable
1095 @end table
1096
1097
1098
1099 @node BESY0
1100 @section @code{BESY0} --- Bessel function of the second kind of order 0
1101 @findex @code{BESY0} intrinsic
1102 @findex @code{DBESY0} intrinsic
1103 @cindex Bessel
1104
1105 @table @asis
1106 @item @emph{Description}:
1107 @code{BESY0(X)} computes the Bessel function of the second kind of order 0
1108 of @var{X}.
1109
1110 @item @emph{Option}:
1111 gnu
1112
1113 @item @emph{Class}:
1114 elemental function
1115
1116 @item @emph{Syntax}:
1117 @code{X = BESY0(X)}
1118
1119 @item @emph{Arguments}:
1120 @multitable @columnfractions .15 .80
1121 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1122 @end multitable
1123
1124 @item @emph{Return value}:
1125 The return value is a scalar of type @code{REAL(*)}.
1126
1127 @item @emph{Example}:
1128 @smallexample
1129 program test_besy0
1130   real(8) :: x = 0.0_8
1131   x = besy0(x)
1132 end program test_besy0
1133 @end smallexample
1134
1135 @item @emph{Specific names}:
1136 @multitable @columnfractions .24 .24 .24 .24
1137 @item Name            @tab Argument          @tab Return type       @tab Option
1138 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab gnu
1139 @end multitable
1140 @end table
1141
1142
1143
1144 @node BESY1
1145 @section @code{BESY1} --- Bessel function of the second kind of order 1
1146 @findex @code{BESY1} intrinsic
1147 @findex @code{DBESY1} intrinsic
1148 @cindex Bessel
1149
1150 @table @asis
1151 @item @emph{Description}:
1152 @code{BESY1(X)} computes the Bessel function of the second kind of order 1
1153 of @var{X}.
1154
1155 @item @emph{Option}:
1156 gnu
1157
1158 @item @emph{Class}:
1159 elemental function
1160
1161 @item @emph{Syntax}:
1162 @code{X = BESY1(X)}
1163
1164 @item @emph{Arguments}:
1165 @multitable @columnfractions .15 .80
1166 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1167 @end multitable
1168
1169 @item @emph{Return value}:
1170 The return value is a scalar of type @code{REAL(*)}.
1171
1172 @item @emph{Example}:
1173 @smallexample
1174 program test_besy1
1175   real(8) :: x = 1.0_8
1176   x = besy1(x)
1177 end program test_besy1
1178 @end smallexample
1179
1180 @item @emph{Specific names}:
1181 @multitable @columnfractions .24 .24 .24 .24
1182 @item Name            @tab Argument          @tab Return type       @tab Option
1183 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab gnu
1184 @end multitable
1185 @end table
1186
1187
1188
1189 @node BESYN
1190 @section @code{BESYN} --- Bessel function of the second kind
1191 @findex @code{BESYN} intrinsic
1192 @findex @code{DBESYN} intrinsic
1193 @cindex Bessel
1194
1195 @table @asis
1196 @item @emph{Description}:
1197 @code{BESYN(N, X)} computes the Bessel function of the second kind of order
1198 @var{N} of @var{X}.
1199
1200 @item @emph{Option}:
1201 gnu
1202
1203 @item @emph{Class}:
1204 elemental function
1205
1206 @item @emph{Syntax}:
1207 @code{Y = BESYN(N, X)}
1208
1209 @item @emph{Arguments}:
1210 @multitable @columnfractions .15 .80
1211 @item @var{N} @tab The type shall be @code{INTEGER(*)}, and it shall be scalar.
1212 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1213 @end multitable
1214
1215 @item @emph{Return value}:
1216 The return value is a scalar of type @code{REAL(*)}.
1217
1218 @item @emph{Example}:
1219 @smallexample
1220 program test_besyn
1221   real(8) :: x = 1.0_8
1222   x = besyn(5,x)
1223 end program test_besyn
1224 @end smallexample
1225
1226 @item @emph{Specific names}:
1227 @multitable @columnfractions .24 .24 .24 .24
1228 @item Name               @tab Argument            @tab Return type     @tab Option
1229 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)}  @tab gnu
1230 @item                    @tab @code{REAL(8)    X} @tab                 @tab
1231 @end multitable
1232 @end table
1233
1234
1235
1236 @node BIT_SIZE
1237 @section @code{BIT_SIZE} --- Bit size inquiry function
1238 @findex @code{BIT_SIZE} intrinsic
1239 @cindex bit_size
1240
1241 @table @asis
1242 @item @emph{Description}:
1243 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1244 represented by the type of @var{I}.
1245
1246 @item @emph{Option}:
1247 f95, gnu
1248
1249 @item @emph{Class}:
1250 elemental function
1251
1252 @item @emph{Syntax}:
1253 @code{I = BIT_SIZE(I)}
1254
1255 @item @emph{Arguments}:
1256 @multitable @columnfractions .15 .80
1257 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1258 @end multitable
1259
1260 @item @emph{Return value}:
1261 The return value is of type @code{INTEGER(*)}
1262
1263 @item @emph{Example}:
1264 @smallexample
1265 program test_bit_size
1266     integer :: i = 123
1267     integer :: size
1268     size = bit_size(i)
1269     print *, size
1270 end program test_bit_size
1271 @end smallexample
1272 @end table
1273
1274
1275
1276 @node BTEST
1277 @section @code{BTEST} --- Bit test function
1278 @findex @code{BTEST} intrinsic
1279 @cindex BTEST
1280
1281 @table @asis
1282 @item @emph{Description}:
1283 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1284 in @var{I} is set.
1285
1286 @item @emph{Option}:
1287 f95, gnu
1288
1289 @item @emph{Class}:
1290 elemental function
1291
1292 @item @emph{Syntax}:
1293 @code{I = BTEST(I,POS)}
1294
1295 @item @emph{Arguments}:
1296 @multitable @columnfractions .15 .80
1297 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1298 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1299 @end multitable
1300
1301 @item @emph{Return value}:
1302 The return value is of type @code{LOGICAL}
1303
1304 @item @emph{Example}:
1305 @smallexample
1306 program test_btest
1307     integer :: i = 32768 + 1024 + 64
1308     integer :: pos
1309     logical :: bool
1310     do pos=0,16
1311         bool = btest(i, pos)
1312         print *, pos, bool
1313     end do
1314 end program test_btest
1315 @end smallexample
1316 @end table
1317
1318
1319
1320 @node CEILING
1321 @section @code{CEILING} --- Integer ceiling function
1322 @findex @code{CEILING} intrinsic
1323 @cindex CEILING
1324
1325 @table @asis
1326 @item @emph{Description}:
1327 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
1328
1329 @item @emph{Option}:
1330 f95, gnu
1331
1332 @item @emph{Class}:
1333 elemental function
1334
1335 @item @emph{Syntax}:
1336 @code{I = CEILING(X[,KIND])}
1337
1338 @item @emph{Arguments}:
1339 @multitable @columnfractions .15 .80
1340 @item @var{X} @tab The type shall be @code{REAL(*)}.
1341 @item @var{KIND} @tab Optional scaler integer initialization expression.
1342 @end multitable
1343
1344 @item @emph{Return value}:
1345 The return value is of type @code{INTEGER(KIND)}
1346
1347 @item @emph{Example}:
1348 @smallexample
1349 program test_ceiling
1350     real :: x = 63.29
1351     real :: y = -63.59
1352     print *, ceiling(x) ! returns 64
1353     print *, ceiling(y) ! returns -63
1354 end program test_ceiling
1355 @end smallexample
1356 @end table
1357
1358
1359
1360 @node CHAR
1361 @section @code{CHAR} --- Character conversion function
1362 @findex @code{CHAR} intrinsic
1363 @cindex CHAR
1364
1365 @table @asis
1366 @item @emph{Description}:
1367 @code{CHAR(I,[KIND])} returns the character represented by the integer @var{I}.
1368
1369 @item @emph{Option}:
1370 f95, gnu
1371
1372 @item @emph{Class}:
1373 elemental function
1374
1375 @item @emph{Syntax}:
1376 @code{C = CHAR(I[,KIND])}
1377
1378 @item @emph{Arguments}:
1379 @multitable @columnfractions .15 .80
1380 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1381 @item @var{KIND} @tab Optional scaler integer initialization expression.
1382 @end multitable
1383
1384 @item @emph{Return value}:
1385 The return value is of type @code{CHARACTER(1)}
1386
1387 @item @emph{Example}:
1388 @smallexample
1389 program test_char
1390     integer :: i = 74
1391     character(1) :: c
1392     c = char(i)
1393     print *, i, c ! returns 'J'
1394 end program test_char
1395 @end smallexample
1396 @end table
1397
1398
1399
1400 @node CMPLX
1401 @section @code{CMPLX} --- Complex conversion function
1402 @findex @code{CMPLX} intrinsic
1403 @cindex CMPLX
1404
1405 @table @asis
1406 @item @emph{Description}:
1407 @code{CMPLX(X,[Y,KIND])} returns a complex number where @var{X} is converted to
1408 the real component.  If @var{Y} is present it is converted to the imaginary
1409 component.  If @var{Y} is not present then the imaginary component is set to
1410 0.0.  If @var{X} is complex then @var{Y} must not be present.
1411
1412 @item @emph{Option}:
1413 f95, gnu
1414
1415 @item @emph{Class}:
1416 elemental function
1417
1418 @item @emph{Syntax}:
1419 @code{C = CMPLX(X[,Y,KIND])}
1420
1421 @item @emph{Arguments}:
1422 @multitable @columnfractions .15 .80
1423 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.
1424 @item @var{Y} @tab Optional, allowed if @var{X} is not @code{COMPLEX(*)}.  May be @code{INTEGER(*)} or @code{REAL(*)}.
1425 @item @var{KIND} @tab Optional scaler integer initialization expression.
1426 @end multitable
1427
1428 @item @emph{Return value}:
1429 The return value is of type @code{COMPLEX(*)}
1430
1431 @item @emph{Example}:
1432 @smallexample
1433 program test_cmplx
1434     integer :: i = 42
1435     real :: x = 3.14
1436     complex :: z
1437     z = cmplx(i, x)
1438     print *, z, cmplx(x)
1439 end program test_cmplx
1440 @end smallexample
1441 @end table
1442
1443
1444
1445 @node COMMAND_ARGUMENT_COUNT
1446 @section @code{COMMAND_ARGUMENT_COUNT} --- Argument count function
1447 @findex @code{COMMAND_ARGUMENT_COUNT} intrinsic
1448 @cindex command argument count
1449
1450 @table @asis
1451 @item @emph{Description}:
1452 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
1453 command line when the containing program was invoked.
1454
1455 @item @emph{Option}:
1456 f2003, gnu
1457
1458 @item @emph{Class}:
1459 non-elemental function
1460
1461 @item @emph{Syntax}:
1462 @code{I = COMMAND_ARGUMENT_COUNT()}
1463
1464 @item @emph{Arguments}:
1465 @multitable @columnfractions .15 .80
1466 @item None
1467 @end multitable
1468
1469 @item @emph{Return value}:
1470 The return value is of type @code{INTEGER(4)}
1471
1472 @item @emph{Example}:
1473 @smallexample
1474 program test_command_argument_count
1475     integer :: count
1476     count = command_argument_count()
1477     print *, count
1478 end program test_command_argument_count
1479 @end smallexample
1480 @end table
1481
1482
1483
1484 @node CONJG
1485 @section @code{CONJG} --- Complex conjugate function
1486 @findex @code{CONJG} intrinsic
1487 @findex @code{DCONJG} intrinsic
1488 @cindex complex conjugate
1489 @table @asis
1490 @item @emph{Description}:
1491 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
1492 then the result is @code{(x, -y)}
1493
1494 @item @emph{Option}:
1495 f95, gnu
1496
1497 @item @emph{Class}:
1498 elemental function
1499
1500 @item @emph{Syntax}:
1501 @code{Z = CONJG(Z)}
1502
1503 @item @emph{Arguments}:
1504 @multitable @columnfractions .15 .80
1505 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
1506 @end multitable
1507
1508 @item @emph{Return value}:
1509 The return value is of type @code{COMPLEX(*)}.
1510
1511 @item @emph{Example}:
1512 @smallexample
1513 program test_conjg
1514     complex :: z = (2.0, 3.0)
1515     complex(8) :: dz = (2.71_8, -3.14_8)
1516     z= conjg(z)
1517     print *, z
1518     dz = dconjg(dz)
1519     print *, dz
1520 end program test_conjg
1521 @end smallexample
1522
1523 @item @emph{Specific names}:
1524 @multitable @columnfractions .24 .24 .24 .24
1525 @item Name             @tab Argument             @tab Return type          @tab Option
1526 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)}    @tab gnu
1527 @end multitable
1528 @end table
1529
1530
1531
1532 @node COS
1533 @section @code{COS} --- Cosine function
1534 @findex @code{COS} intrinsic
1535 @findex @code{DCOS} intrinsic
1536 @findex @code{ZCOS} intrinsic
1537 @findex @code{CDCOS} intrinsic
1538 @cindex cosine
1539
1540 @table @asis
1541 @item @emph{Description}:
1542 @code{COS(X)} computes the cosine of @var{X}.
1543
1544 @item @emph{Option}:
1545 f95, gnu
1546
1547 @item @emph{Class}:
1548 elemental function
1549
1550 @item @emph{Syntax}:
1551 @code{X = COS(X)}
1552
1553 @item @emph{Arguments}:
1554 @multitable @columnfractions .15 .80
1555 @item @var{X} @tab The type shall be @code{REAL(*)} or
1556 @code{COMPLEX(*)}.
1557 @end multitable
1558
1559 @item @emph{Return value}:
1560 The return value has the same type and kind as @var{X}.
1561
1562 @item @emph{Example}:
1563 @smallexample
1564 program test_cos
1565   real :: x = 0.0
1566   x = cos(x)
1567 end program test_cos
1568 @end smallexample
1569
1570 @item @emph{Specific names}:
1571 @multitable @columnfractions .24 .24 .24 .24
1572 @item Name            @tab Argument          @tab Return type     @tab Option
1573 @item @code{DCOS(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab f95, gnu
1574 @item @code{CCOS(X)}@tab @code{COMPLEX(4) X}@tab @code{COMPLEX(4)}@tab f95, gnu
1575 @item @code{ZCOS(X)}@tab @code{COMPLEX(8) X}@tab @code{COMPLEX(8)}@tab f95, gnu
1576 @item @code{CDCOS(X)}@tab @code{COMPLEX(8) X}@tab @code{COMPLEX(8)}@tab f95, gnu
1577 @end multitable
1578 @end table
1579
1580
1581
1582 @node COSH
1583 @section @code{COSH} --- Hyperbolic cosine function
1584 @findex @code{COSH} intrinsic
1585 @findex @code{DCOSH} intrinsic
1586 @cindex hyperbolic cosine
1587
1588 @table @asis
1589 @item @emph{Description}:
1590 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
1591
1592 @item @emph{Option}:
1593 f95, gnu
1594
1595 @item @emph{Class}:
1596 elemental function
1597
1598 @item @emph{Syntax}:
1599 @code{X = COSH(X)}
1600
1601 @item @emph{Arguments}:
1602 @multitable @columnfractions .15 .80
1603 @item @var{X} @tab The type shall be @code{REAL(*)}.
1604 @end multitable
1605
1606 @item @emph{Return value}:
1607 The return value is of type @code{REAL(*)} and it is positive
1608 (@math{ \cosh (x) \geq 0 }.
1609
1610 @item @emph{Example}:
1611 @smallexample
1612 program test_cosh
1613   real(8) :: x = 1.0_8
1614   x = cosh(x)
1615 end program test_cosh
1616 @end smallexample
1617
1618 @item @emph{Specific names}:
1619 @multitable @columnfractions .24 .24 .24 .24
1620 @item Name            @tab Argument          @tab Return type       @tab Option
1621 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
1622 @end multitable
1623 @end table
1624
1625
1626
1627 @node COUNT
1628 @section @code{COUNT} --- Count function
1629 @findex @code{COUNT} intrinsic
1630 @cindex count
1631
1632 @table @asis
1633 @item @emph{Description}:
1634 @code{COUNT(MASK[,DIM])} counts the number of @code{.TRUE.} elements of
1635 @var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
1636 taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
1637 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{MASK}.
1638
1639 @item @emph{Option}:
1640 f95, gnu
1641
1642 @item @emph{Class}:
1643 transformational function
1644
1645 @item @emph{Syntax}:
1646 @code{I = COUNT(MASK[,DIM])}
1647
1648 @item @emph{Arguments}:
1649 @multitable @columnfractions .15 .80
1650 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
1651 @item @var{DIM}  @tab The type shall be @code{INTEGER}.
1652 @end multitable
1653
1654 @item @emph{Return value}:
1655 The return value is of type @code{INTEGER} with rank equal to that of
1656 @var{MASK}.
1657
1658 @item @emph{Example}:
1659 @smallexample
1660 program test_count
1661     integer, dimension(2,3) :: a, b
1662     logical, dimension(2,3) :: mask
1663     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
1664     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
1665     print '(3i3)', a(1,:)
1666     print '(3i3)', a(2,:)
1667     print *
1668     print '(3i3)', b(1,:)
1669     print '(3i3)', b(2,:)
1670     print *
1671     mask = a.ne.b
1672     print '(3l3)', mask(1,:)
1673     print '(3l3)', mask(2,:)
1674     print *
1675     print '(3i3)', count(mask)
1676     print *
1677     print '(3i3)', count(mask, 1)
1678     print *
1679     print '(3i3)', count(mask, 2)
1680 end program test_count
1681 @end smallexample
1682 @end table
1683
1684
1685
1686 @node CPU_TIME
1687 @section @code{CPU_TIME} --- CPU elapsed time in seconds
1688 @findex @code{CPU_TIME} intrinsic
1689 @cindex CPU_TIME
1690
1691 @table @asis
1692 @item @emph{Description}:
1693 Returns a @code{REAL} value representing the elapsed CPU time in seconds.  This
1694 is useful for testing segments of code to determine execution time.
1695
1696 @item @emph{Option}:
1697 f95, gnu
1698
1699 @item @emph{Class}:
1700 subroutine
1701
1702 @item @emph{Syntax}:
1703 @code{CPU_TIME(X)}
1704
1705 @item @emph{Arguments}:
1706 @multitable @columnfractions .15 .80
1707 @item @var{X} @tab The type shall be @code{REAL} with intent out.
1708 @end multitable
1709
1710 @item @emph{Return value}:
1711 None
1712
1713 @item @emph{Example}:
1714 @smallexample
1715 program test_cpu_time
1716     real :: start, finish
1717     call cpu_time(start)
1718         ! put code to test here
1719     call cpu_time(finish)
1720     print '("Time = ",f6.3," seconds.")',finish-start
1721 end program test_cpu_time
1722 @end smallexample
1723 @end table
1724
1725
1726
1727 @node CSHIFT
1728 @section @code{CSHIFT} --- Circular shift function
1729 @findex @code{CSHIFT} intrinsic
1730 @cindex cshift intrinsic
1731
1732 @table @asis
1733 @item @emph{Description}:
1734 @code{CSHIFT(ARRAY, SHIFT[,DIM])} performs a circular shift on elements of
1735 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
1736 taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
1737 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
1738 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
1739 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
1740 sections of @var{ARRAY} along the given dimension are shifted.  Elements
1741 shifted out one end of each rank one section are shifted back in the other end.
1742
1743 @item @emph{Option}:
1744 f95, gnu
1745
1746 @item @emph{Class}:
1747 transformational function
1748
1749 @item @emph{Syntax}:
1750 @code{A = CSHIFT(A, SHIFT[,DIM])}
1751
1752 @item @emph{Arguments}:
1753 @multitable @columnfractions .15 .80
1754 @item @var{ARRAY}  @tab May be any type, not scaler.
1755 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
1756 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
1757 @end multitable
1758
1759 @item @emph{Return value}:
1760 Returns an array of same type and rank as the @var{ARRAY} argument.
1761
1762 @item @emph{Example}:
1763 @smallexample
1764 program test_cshift
1765     integer, dimension(3,3) :: a
1766     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
1767     print '(3i3)', a(1,:)
1768     print '(3i3)', a(2,:)
1769     print '(3i3)', a(3,:)
1770     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
1771     print *
1772     print '(3i3)', a(1,:)
1773     print '(3i3)', a(2,:)
1774     print '(3i3)', a(3,:)
1775 end program test_cshift
1776 @end smallexample
1777 @end table
1778
1779
1780
1781 @node DATE_AND_TIME
1782 @section @code{DATE_AND_TIME} --- Date and time subroutine
1783 @findex @code{DATE_AND_TIME} intrinsic
1784 @cindex DATE_AND_TIME
1785
1786 @table @asis
1787 @item @emph{Description}:
1788 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
1789 time information from the real-time system clock.  @var{DATE} is
1790 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
1791 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
1792 representing the difference with respect to Coordinated Universal Time (UTC).
1793 Unavailable time and date parameters return blanks.
1794
1795 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
1796
1797 @multitable @columnfractions .15 .30 .60
1798 @item @tab @code{VALUE(1)}: @tab The year
1799 @item @tab @code{VALUE(2)}: @tab The month
1800 @item @tab @code{VALUE(3)}: @tab The day of the month
1801 @item @tab @code{VAlUE(4)}: @tab Time difference with UTC in minutes
1802 @item @tab @code{VALUE(5)}: @tab The hour of the day
1803 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
1804 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
1805 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
1806 @end multitable
1807
1808 @item @emph{Option}:
1809 f95, gnu
1810
1811 @item @emph{Class}:
1812 subroutine
1813
1814 @item @emph{Syntax}:
1815 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
1816
1817 @item @emph{Arguments}:
1818 @multitable @columnfractions .15 .80
1819 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
1820 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
1821 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
1822 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
1823 @end multitable
1824
1825 @item @emph{Return value}:
1826 None
1827
1828 @item @emph{Example}:
1829 @smallexample
1830 program test_time_and_date
1831     character(8)  :: date
1832     character(10) :: time
1833     character(5)  :: zone
1834     integer,dimension(8) :: values
1835     ! using keyword arguments
1836     call date_and_time(date,time,zone,values)
1837     call date_and_time(DATE=date,ZONE=zone)
1838     call date_and_time(TIME=time)
1839     call date_and_time(VALUES=values)
1840     print '(a,2x,a,2x,a)', date, time, zone
1841     print '(8i5))', values
1842 end program test_time_and_date
1843 @end smallexample
1844 @end table
1845
1846
1847
1848 @node DBLE
1849 @section @code{DBLE} --- Double conversion function
1850 @findex @code{DBLE} intrinsic
1851 @cindex double conversion
1852
1853 @table @asis
1854 @item @emph{Description}:
1855 @code{DBLE(X)} Converts @var{X} to double precision real type.
1856 @code{DFLOAT} is an alias for @code{DBLE}
1857
1858 @item @emph{Option}:
1859 f95, gnu
1860
1861 @item @emph{Class}:
1862 elemental function
1863
1864 @item @emph{Syntax}:
1865 @code{X = DBLE(X)}
1866 @code{X = DFLOAT(X)}
1867
1868 @item @emph{Arguments}:
1869 @multitable @columnfractions .15 .80
1870 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.
1871 @end multitable
1872
1873 @item @emph{Return value}:
1874 The return value is of type double precision real.
1875
1876 @item @emph{Example}:
1877 @smallexample
1878 program test_dble
1879     real    :: x = 2.18
1880     integer :: i = 5
1881     complex :: z = (2.3,1.14)
1882     print *, dble(x), dble(i), dfloat(z)
1883 end program test_dble
1884 @end smallexample
1885 @end table
1886
1887
1888
1889 @node DCMPLX
1890 @section @code{DCMPLX} --- Double complex conversion function
1891 @findex @code{DCMPLX} intrinsic
1892 @cindex DCMPLX
1893
1894 @table @asis
1895 @item @emph{Description}:
1896 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
1897 converted to the real component.  If @var{Y} is present it is converted to the
1898 imaginary component.  If @var{Y} is not present then the imaginary component is
1899 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
1900
1901 @item @emph{Option}:
1902 f95, gnu
1903
1904 @item @emph{Class}:
1905 elemental function
1906
1907 @item @emph{Syntax}:
1908 @code{C = DCMPLX(X)}
1909 @code{C = DCMPLX(X,Y)}
1910
1911 @item @emph{Arguments}:
1912 @multitable @columnfractions .15 .80
1913 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.
1914 @item @var{Y} @tab Optional if @var{X} is not @code{COMPLEX(*)}. May be @code{INTEGER(*)} or @code{REAL(*)}.
1915 @end multitable
1916
1917 @item @emph{Return value}:
1918 The return value is of type @code{COMPLEX(8)}
1919
1920 @item @emph{Example}:
1921 @smallexample
1922 program test_dcmplx
1923     integer :: i = 42
1924     real :: x = 3.14
1925     complex :: z
1926     z = cmplx(i, x)
1927     print *, dcmplx(i)
1928     print *, dcmplx(x)
1929     print *, dcmplx(z)
1930     print *, dcmplx(x,i)
1931 end program test_dcmplx
1932 @end smallexample
1933 @end table
1934
1935
1936
1937 @node DFLOAT
1938 @section @code{DFLOAT} --- Double conversion function
1939 @findex @code{DFLOAT} intrinsic
1940 @cindex double float conversion
1941
1942 @table @asis
1943 @item @emph{Description}:
1944 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
1945 @code{DFLOAT} is an alias for @code{DBLE}.  See @code{DBLE}.
1946 @end table
1947
1948
1949
1950 @node DIGITS
1951 @section @code{DIGITS} --- Significant digits function
1952 @findex @code{DIGITS} intrinsic
1953 @cindex digits, significant
1954
1955 @table @asis
1956 @item @emph{Description}:
1957 @code{DIGITS(X)} returns the number of significant digits of the internal model
1958 representation of @var{X}.  For example, on a system using a 32-bit
1959 floating point representation, a default real number would likely return 24.
1960
1961 @item @emph{Option}:
1962 f95, gnu
1963
1964 @item @emph{Class}:
1965 inquiry function
1966
1967 @item @emph{Syntax}:
1968 @code{C = DIGITS(X)}
1969
1970 @item @emph{Arguments}:
1971 @multitable @columnfractions .15 .80
1972 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
1973 @end multitable
1974
1975 @item @emph{Return value}:
1976 The return value is of type @code{INTEGER}.
1977
1978 @item @emph{Example}:
1979 @smallexample
1980 program test_digits
1981     integer :: i = 12345
1982     real :: x = 3.143
1983     real(8) :: y = 2.33
1984     print *, digits(i)
1985     print *, digits(x)
1986     print *, digits(y)
1987 end program test_digits
1988 @end smallexample
1989 @end table
1990
1991
1992
1993 @node DIM
1994 @section @code{DIM} --- Dim function
1995 @findex @code{DIM} intrinsic
1996 @findex @code{IDIM} intrinsic
1997 @findex @code{DDIM} intrinsic
1998 @cindex dim
1999
2000 @table @asis
2001 @item @emph{Description}:
2002 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
2003 otherwise returns zero.
2004
2005 @item @emph{Option}:
2006 f95, gnu
2007
2008 @item @emph{Class}:
2009 elemental function
2010
2011 @item @emph{Syntax}:
2012 @code{X = DIM(X,Y)}
2013
2014 @item @emph{Arguments}:
2015 @multitable @columnfractions .15 .80
2016 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
2017 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
2018 @end multitable
2019
2020 @item @emph{Return value}:
2021 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
2022
2023 @item @emph{Example}:
2024 @smallexample
2025 program test_dim
2026     integer :: i
2027     real(8) :: x
2028     i = dim(4, 15)
2029     x = dim(4.345_8, 2.111_8)
2030     print *, i
2031     print *, x
2032 end program test_dim
2033 @end smallexample
2034
2035 @item @emph{Specific names}:
2036 @multitable @columnfractions .24 .24 .24 .24
2037 @item Name            @tab Argument          @tab Return type       @tab Option
2038 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab gnu
2039 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}  @tab @code{REAL(8)} @tab gnu
2040 @end multitable
2041 @end table
2042
2043
2044
2045 @node DOT_PRODUCT
2046 @section @code{DOT_PRODUCT} --- Dot product function
2047 @findex @code{DOT_PRODUCT} intrinsic
2048 @cindex Dot product
2049
2050 @table @asis
2051 @item @emph{Description}:
2052 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
2053 @var{X} and @var{Y}.  The two vectors may be either numeric or logical
2054 and must be arrays of rank one and of equal size. If the vectors are
2055 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
2056 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
2057 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
2058
2059 @item @emph{Option}:
2060 f95
2061
2062 @item @emph{Class}:
2063 transformational function
2064
2065 @item @emph{Syntax}:
2066 @code{S = DOT_PRODUCT(X,Y)}
2067
2068 @item @emph{Arguments}:
2069 @multitable @columnfractions .15 .80
2070 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2071 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2072 @end multitable
2073
2074 @item @emph{Return value}:
2075 If the arguments are numeric, the return value is a scaler of numeric type,
2076 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.  If the arguments are
2077 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
2078
2079 @item @emph{Example}:
2080 @smallexample
2081 program test_dot_prod
2082     integer, dimension(3) :: a, b
2083     a = (/ 1, 2, 3 /)
2084     b = (/ 4, 5, 6 /)
2085     print '(3i3)', a
2086     print *
2087     print '(3i3)', b
2088     print *
2089     print *, dot_product(a,b)
2090 end program test_dot_prod
2091 @end smallexample
2092 @end table
2093
2094
2095
2096 @node DPROD
2097 @section @code{DPROD} --- Double product function
2098 @findex @code{DPROD} intrinsic
2099 @cindex Double product
2100
2101 @table @asis
2102 @item @emph{Description}:
2103 @code{DPROD(X,Y)} returns the product @code{X*Y}.
2104
2105 @item @emph{Option}:
2106 f95, gnu
2107
2108 @item @emph{Class}:
2109 elemental function
2110
2111 @item @emph{Syntax}:
2112 @code{D = DPROD(X,Y)}
2113
2114 @item @emph{Arguments}:
2115 @multitable @columnfractions .15 .80
2116 @item @var{X} @tab The type shall be @code{REAL}.
2117 @item @var{Y} @tab The type shall be @code{REAL}.
2118 @end multitable
2119
2120 @item @emph{Return value}:
2121 The return value is of type @code{REAL(8)}.
2122
2123 @item @emph{Example}:
2124 @smallexample
2125 program test_dprod
2126     integer :: i
2127     real :: x = 5.2
2128     real :: y = 2.3
2129     real(8) :: d
2130     d = dprod(x,y)
2131     print *, d
2132 end program test_dprod
2133 @end smallexample
2134 @end table
2135
2136
2137
2138 @node DREAL
2139 @section @code{DREAL} --- Double real part function
2140 @findex @code{DREAL} intrinsic
2141 @cindex Double real part
2142
2143 @table @asis
2144 @item @emph{Description}:
2145 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
2146
2147 @item @emph{Option}:
2148 gnu
2149
2150 @item @emph{Class}:
2151 elemental function
2152
2153 @item @emph{Syntax}:
2154 @code{D = DREAL(Z)}
2155
2156 @item @emph{Arguments}:
2157 @multitable @columnfractions .15 .80
2158 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
2159 @end multitable
2160
2161 @item @emph{Return value}:
2162 The return value is of type @code{REAL(8)}.
2163
2164 @item @emph{Example}:
2165 @smallexample
2166 program test_dreal
2167     complex(8) :: z = (1.3_8,7.2_8)
2168     print *, dreal(z)
2169 end program test_dreal
2170 @end smallexample
2171 @end table
2172
2173
2174
2175 @node DTIME
2176 @section @code{DTIME} --- Execution time subroutine (or function)
2177 @findex @code{DTIME} intrinsic
2178 @cindex dtime subroutine
2179
2180 @table @asis
2181 @item @emph{Description}:
2182 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
2183 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
2184 returns the user and system components of this time in @code{TARRAY(1)} and
2185 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
2186 TARRAY(2)}.
2187
2188 Subsequent invocations of @code{DTIME} return values accumulated since the
2189 previous invocation.
2190
2191 On some systems, the underlying timings are represented using types with
2192 sufficiently small limits that overflows (wraparounds) are possible, such as
2193 32-bit types. Therefore, the values returned by this intrinsic might be, or
2194 become, negative, or numerically less than previous values, during a single
2195 run of the compiled program.
2196
2197 If @code{DTIME} is invoked as a function, it can not be invoked as a
2198 subroutine, and vice versa.
2199
2200 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
2201
2202 @multitable @columnfractions .15 .30 .60
2203 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
2204 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
2205 @item @tab @code{RESULT}: @tab Run time since start in seconds.
2206 @end multitable
2207
2208 @item @emph{Option}:
2209 gnu
2210
2211 @item @emph{Class}:
2212 subroutine
2213
2214 @item @emph{Syntax}:
2215 @multitable @columnfractions .80
2216 @item @code{CALL DTIME(TARRAY, RESULT)}.
2217 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
2218 @end multitable
2219
2220 @item @emph{Arguments}:
2221 @multitable @columnfractions .15 .80
2222 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
2223 @item @var{RESULT}@tab The type shall be @code{REAL}.
2224 @end multitable
2225
2226 @item @emph{Return value}:
2227 Elapsed time in seconds since the start of program execution.
2228
2229 @item @emph{Example}:
2230 @smallexample
2231 program test_dtime
2232     integer(8) :: i, j
2233     real, dimension(2) :: tarray
2234     real :: result
2235     call dtime(tarray, result)
2236     print *, result
2237     print *, tarray(1)
2238     print *, tarray(2)
2239     do i=1,100000000    ! Just a delay
2240         j = i * i - i
2241     end do
2242     call dtime(tarray, result)
2243     print *, result
2244     print *, tarray(1)
2245     print *, tarray(2)
2246 end program test_dtime
2247 @end smallexample
2248 @end table
2249
2250
2251
2252 @node EOSHIFT
2253 @section @code{EOSHIFT} --- End-off shift function
2254 @findex @code{EOSHIFT} intrinsic
2255 @cindex eoshift intrinsic
2256
2257 @table @asis
2258 @item @emph{Description}:
2259 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
2260 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
2261 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
2262 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
2263 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
2264 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
2265 then all complete rank one sections of @var{ARRAY} along the given dimension are
2266 shifted.  Elements shifted out one end of each rank one section are dropped.  If
2267 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
2268 is copied back in the other end.  If @var{BOUNDARY} is not present then the
2269 following are copied in depending on the type of @var{ARRAY}.
2270
2271 @multitable @columnfractions .15 .80
2272 @item @emph{Array Type} @tab @emph{Boundary Value}
2273 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
2274 @item Logical  @tab @code{.FALSE.}.
2275 @item Character(@var{len}) @tab @var{len} blanks.
2276 @end multitable
2277
2278 @item @emph{Option}:
2279 f95, gnu
2280
2281 @item @emph{Class}:
2282 transformational function
2283
2284 @item @emph{Syntax}:
2285 @code{A = EOSHIFT(A, SHIFT[,BOUNDARY, DIM])}
2286
2287 @item @emph{Arguments}:
2288 @multitable @columnfractions .15 .80
2289 @item @var{ARRAY}  @tab May be any type, not scaler.
2290 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2291 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
2292 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2293 @end multitable
2294
2295 @item @emph{Return value}:
2296 Returns an array of same type and rank as the @var{ARRAY} argument.
2297
2298 @item @emph{Example}:
2299 @smallexample
2300 program test_eoshift
2301     integer, dimension(3,3) :: a
2302     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2303     print '(3i3)', a(1,:)
2304     print '(3i3)', a(2,:)
2305     print '(3i3)', a(3,:)
2306     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
2307     print *
2308     print '(3i3)', a(1,:)
2309     print '(3i3)', a(2,:)
2310     print '(3i3)', a(3,:)
2311 end program test_eoshift
2312 @end smallexample
2313 @end table
2314
2315
2316
2317 @node EPSILON
2318 @section @code{EPSILON} --- Epsilon function
2319 @findex @code{EPSILON} intrinsic
2320 @cindex epsilon, significant
2321
2322 @table @asis
2323 @item @emph{Description}:
2324 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
2325
2326 @item @emph{Option}:
2327 f95, gnu
2328
2329 @item @emph{Class}:
2330 inquiry function
2331
2332 @item @emph{Syntax}:
2333 @code{C = EPSILON(X)}
2334
2335 @item @emph{Arguments}:
2336 @multitable @columnfractions .15 .80
2337 @item @var{X} @tab The type shall be @code{REAL(*)}.
2338 @end multitable
2339
2340 @item @emph{Return value}:
2341 The return value is of same type as the argument.
2342
2343 @item @emph{Example}:
2344 @smallexample
2345 program test_epsilon
2346     real :: x = 3.143
2347     real(8) :: y = 2.33
2348     print *, EPSILON(x)
2349     print *, EPSILON(y)
2350 end program test_epsilon
2351 @end smallexample
2352 @end table
2353
2354
2355
2356 @node ERF
2357 @section @code{ERF} --- Error function
2358 @findex @code{ERF} intrinsic
2359 @cindex error function
2360
2361 @table @asis
2362 @item @emph{Description}:
2363 @code{ERF(X)} computes the error function of @var{X}.
2364
2365 @item @emph{Option}:
2366 gnu
2367
2368 @item @emph{Class}:
2369 elemental function
2370
2371 @item @emph{Syntax}:
2372 @code{X = ERF(X)}
2373
2374 @item @emph{Arguments}:
2375 @multitable @columnfractions .15 .80
2376 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
2377 @end multitable
2378
2379 @item @emph{Return value}:
2380 The return value is a scalar of type @code{REAL(*)} and it is positive
2381 (@math{ - 1 \leq erf (x) \leq 1 }.
2382
2383 @item @emph{Example}:
2384 @smallexample
2385 program test_erf
2386   real(8) :: x = 0.17_8
2387   x = erf(x)
2388 end program test_erf
2389 @end smallexample
2390
2391 @item @emph{Specific names}:
2392 @multitable @columnfractions .24 .24 .24 .24
2393 @item Name            @tab Argument          @tab Return type       @tab Option
2394 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab gnu
2395 @end multitable
2396 @end table
2397
2398
2399
2400 @node ERFC
2401 @section @code{ERFC} --- Error function
2402 @findex @code{ERFC} intrinsic
2403 @cindex error function
2404
2405 @table @asis
2406 @item @emph{Description}:
2407 @code{ERFC(X)} computes the complementary error function of @var{X}.
2408
2409 @item @emph{Option}:
2410 gnu
2411
2412 @item @emph{Class}:
2413 elemental function
2414
2415 @item @emph{Syntax}:
2416 @code{X = ERFC(X)}
2417
2418 @item @emph{Arguments}:
2419 @multitable @columnfractions .15 .80
2420 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
2421 @end multitable
2422
2423 @item @emph{Return value}:
2424 The return value is a scalar of type @code{REAL(*)} and it is positive
2425 (@math{ 0 \leq erfc (x) \leq 2 }.
2426
2427 @item @emph{Example}:
2428 @smallexample
2429 program test_erfc
2430   real(8) :: x = 0.17_8
2431   x = erfc(x)
2432 end program test_erfc
2433 @end smallexample
2434
2435 @item @emph{Specific names}:
2436 @multitable @columnfractions .24 .24 .24 .24
2437 @item Name            @tab Argument          @tab Return type       @tab Option
2438 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab gnu
2439 @end multitable
2440 @end table
2441
2442
2443
2444 @node ETIME
2445 @section @code{ETIME} --- Execution time subroutine (or function)
2446 @findex @code{ETIME} intrinsic
2447 @cindex ETIME subroutine
2448
2449 @table @asis
2450 @item @emph{Description}:
2451 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
2452 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
2453 returns the user and system components of this time in @code{TARRAY(1)} and
2454 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
2455
2456 On some systems, the underlying timings are represented using types with
2457 sufficiently small limits that overflows (wraparounds) are possible, such as
2458 32-bit types. Therefore, the values returned by this intrinsic might be, or
2459 become, negative, or numerically less than previous values, during a single
2460 run of the compiled program.
2461
2462 If @code{ETIME} is invoked as a function, it can not be invoked as a
2463 subroutine, and vice versa.
2464
2465 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
2466
2467 @multitable @columnfractions .15 .30 .60
2468 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
2469 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
2470 @item @tab @code{RESULT}: @tab Run time since start in seconds.
2471 @end multitable
2472
2473 @item @emph{Option}:
2474 gnu
2475
2476 @item @emph{Class}:
2477 subroutine
2478
2479 @item @emph{Syntax}:
2480 @multitable @columnfractions .8
2481 @item @code{CALL ETIME(TARRAY, RESULT)}.
2482 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
2483 @end multitable
2484
2485 @item @emph{Arguments}:
2486 @multitable @columnfractions .15 .80
2487 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
2488 @item @var{RESULT}@tab The type shall be @code{REAL}.
2489 @end multitable
2490
2491 @item @emph{Return value}:
2492 Elapsed time in seconds since the start of program execution.
2493
2494 @item @emph{Example}:
2495 @smallexample
2496 program test_etime
2497     integer(8) :: i, j
2498     real, dimension(2) :: tarray
2499     real :: result
2500     call ETIME(tarray, result)
2501     print *, result
2502     print *, tarray(1)
2503     print *, tarray(2)
2504     do i=1,100000000    ! Just a delay
2505         j = i * i - i
2506     end do
2507     call ETIME(tarray, result)
2508     print *, result
2509     print *, tarray(1)
2510     print *, tarray(2)
2511 end program test_etime
2512 @end smallexample
2513 @end table
2514
2515
2516
2517 @node EXIT
2518 @section @code{EXIT} --- Exit the program with status.
2519 @findex @code{EXIT}
2520 @cindex exit
2521
2522 @table @asis
2523 @item @emph{Description}:
2524 @code{EXIT} causes immediate termination of the program with status.  If status
2525 is omitted it returns the canonical @emph{success} for the system.  All Fortran
2526 I/O units are closed.
2527
2528 @item @emph{Option}:
2529 gnu
2530
2531 @item @emph{Class}:
2532 non-elemental subroutine
2533
2534 @item @emph{Syntax}:
2535 @code{CALL EXIT([STATUS])}
2536
2537 @item @emph{Arguments}:
2538 @multitable @columnfractions .15 .80
2539 @item @var{STATUS} @tab The type of the argument shall be @code{INTEGER(*)}.
2540 @end multitable
2541
2542 @item @emph{Return value}:
2543 @code{STATUS} is passed to the parent process on exit.
2544
2545 @item @emph{Example}:
2546 @smallexample
2547 program test_exit
2548   integer :: STATUS = 0
2549   print *, 'This program is going to exit.'
2550   call EXIT(STATUS)
2551 end program test_exit
2552 @end smallexample
2553 @end table
2554
2555
2556
2557 @node EXP
2558 @section @code{EXP} --- Exponential function
2559 @findex @code{EXP} intrinsic
2560 @findex @code{DEXP} intrinsic
2561 @findex @code{ZEXP} intrinsic
2562 @findex @code{CDEXP} intrinsic
2563 @cindex exponential
2564
2565 @table @asis
2566 @item @emph{Description}:
2567 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
2568
2569 @item @emph{Option}:
2570 f95, gnu
2571
2572 @item @emph{Class}:
2573 elemental function
2574
2575 @item @emph{Syntax}:
2576 @code{X = EXP(X)}
2577
2578 @item @emph{Arguments}:
2579 @multitable @columnfractions .15 .80
2580 @item @var{X} @tab The type shall be @code{REAL(*)} or
2581 @code{COMPLEX(*)}.
2582 @end multitable
2583
2584 @item @emph{Return value}:
2585 The return value has same type and kind as @var{X}.
2586
2587 @item @emph{Example}:
2588 @smallexample
2589 program test_exp
2590   real :: x = 1.0
2591   x = exp(x)
2592 end program test_exp
2593 @end smallexample
2594
2595 @item @emph{Specific names}:
2596 @multitable @columnfractions .24 .24 .24 .24
2597 @item Name            @tab Argument          @tab Return type       @tab Option
2598 @item @code{DEXP(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
2599 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
2600 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
2601 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
2602 @end multitable
2603 @end table
2604
2605
2606
2607 @node EXPONENT
2608 @section @code{EXPONENT} --- Exponent function
2609 @findex @code{EXPONENT} intrinsic
2610 @cindex exponent function
2611
2612 @table @asis
2613 @item @emph{Description}:
2614 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
2615 is zero the value returned is zero.
2616
2617 @item @emph{Option}:
2618 f95, gnu
2619
2620 @item @emph{Class}:
2621 elemental function
2622
2623 @item @emph{Syntax}:
2624 @code{I = EXPONENT(X)}
2625
2626 @item @emph{Arguments}:
2627 @multitable @columnfractions .15 .80
2628 @item @var{X} @tab The type shall be @code{REAL(*)}.
2629 @end multitable
2630
2631 @item @emph{Return value}:
2632 The return value is of type default @code{INTEGER}.
2633
2634 @item @emph{Example}:
2635 @smallexample
2636 program test_exponent
2637   real :: x = 1.0
2638   integer :: i
2639   i = exponent(x)
2640   print *, i
2641   print *, exponent(0.0)
2642 end program test_exponent
2643 @end smallexample
2644 @end table
2645
2646
2647
2648 @node FLOOR
2649 @section @code{FLOOR} --- Integer floor function
2650 @findex @code{FLOOR} intrinsic
2651 @cindex floor
2652
2653 @table @asis
2654 @item @emph{Description}:
2655 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
2656
2657 @item @emph{Option}:
2658 f95, gnu
2659
2660 @item @emph{Class}:
2661 elemental function
2662
2663 @item @emph{Syntax}:
2664 @code{I = FLOOR(X[,KIND])}
2665
2666 @item @emph{Arguments}:
2667 @multitable @columnfractions .15 .80
2668 @item @var{X} @tab The type shall be @code{REAL(*)}.
2669 @item @var{KIND} @tab Optional scaler integer initialization expression.
2670 @end multitable
2671
2672 @item @emph{Return value}:
2673 The return value is of type @code{INTEGER(KIND)}
2674
2675 @item @emph{Example}:
2676 @smallexample
2677 program test_floor
2678     real :: x = 63.29
2679     real :: y = -63.59
2680     print *, floor(x) ! returns 63
2681     print *, floor(y) ! returns -64
2682 end program test_floor
2683 @end smallexample
2684 @end table
2685
2686
2687
2688 @node FNUM
2689 @section @code{FNUM} --- File number function
2690 @findex @code{FNUM} intrinsic
2691 @cindex fnum
2692
2693 @table @asis
2694 @item @emph{Description}:
2695 @code{FNUM(UNIT)} returns the Posix file descriptor number corresponding to the
2696 open Fortran I/O unit @code{UNIT}.
2697
2698 @item @emph{Option}:
2699 gnu
2700
2701 @item @emph{Class}:
2702 non-elemental function
2703
2704 @item @emph{Syntax}:
2705 @code{I = FNUM(UNIT)}
2706
2707 @item @emph{Arguments}:
2708 @multitable @columnfractions .15 .80
2709 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
2710 @end multitable
2711
2712 @item @emph{Return value}:
2713 The return value is of type @code{INTEGER}
2714
2715 @item @emph{Example}:
2716 @smallexample
2717 program test_fnum
2718   integer :: i
2719   open (unit=10, status = "scratch")
2720   i = fnum(10)
2721   print *, i
2722   close (10)
2723 end program test_fnum
2724 @end smallexample
2725 @end table
2726
2727
2728
2729 @node LOG
2730 @section @code{LOG} --- Logarithm function
2731 @findex @code{LOG} intrinsic
2732 @findex @code{ALOG} intrinsic
2733 @findex @code{DLOG} intrinsic
2734 @findex @code{CLOG} intrinsic
2735 @findex @code{ZLOG} intrinsic
2736 @findex @code{CDLOG} intrinsic
2737 @cindex logarithm
2738
2739 @table @asis
2740 @item @emph{Description}:
2741 @code{LOG(X)} computes the logarithm of @var{X}.
2742
2743 @item @emph{Option}:
2744 f95, gnu
2745
2746 @item @emph{Class}:
2747 elemental function
2748
2749 @item @emph{Syntax}:
2750 @code{X = LOG(X)}
2751
2752 @item @emph{Arguments}:
2753 @multitable @columnfractions .15 .80
2754 @item @var{X} @tab The type shall be @code{REAL(*)} or
2755 @code{COMPLEX(*)}.
2756 @end multitable
2757
2758 @item @emph{Return value}:
2759 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
2760 The kind type parameter is the same as @var{X}.
2761
2762 @item @emph{Example}:
2763 @smallexample
2764 program test_log
2765   real(8) :: x = 1.0_8
2766   complex :: z = (1.0, 2.0)
2767   x = log(x)
2768   z = log(z)
2769 end program test_log
2770 @end smallexample
2771
2772 @item @emph{Specific names}:
2773 @multitable @columnfractions .24 .24 .24 .24
2774 @item Name            @tab Argument          @tab Return type       @tab Option
2775 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
2776 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
2777 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
2778 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
2779 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
2780 @end multitable
2781 @end table
2782
2783
2784
2785 @node LOG10
2786 @section @code{LOG10} --- Base 10 logarithm function
2787 @findex @code{LOG10} intrinsic
2788 @findex @code{ALOG10} intrinsic
2789 @findex @code{DLOG10} intrinsic
2790 @cindex logarithm
2791
2792 @table @asis
2793 @item @emph{Description}:
2794 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
2795
2796 @item @emph{Option}:
2797 f95, gnu
2798
2799 @item @emph{Class}:
2800 elemental function
2801
2802 @item @emph{Syntax}:
2803 @code{X = LOG10(X)}
2804
2805 @item @emph{Arguments}:
2806 @multitable @columnfractions .15 .80
2807 @item @var{X} @tab The type shall be @code{REAL(*)} or
2808 @code{COMPLEX(*)}.
2809 @end multitable
2810
2811 @item @emph{Return value}:
2812 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
2813 The kind type parameter is the same as @var{X}.
2814
2815 @item @emph{Example}:
2816 @smallexample
2817 program test_log10
2818   real(8) :: x = 10.0_8
2819   x = log10(x)
2820 end program test_log10
2821 @end smallexample
2822
2823 @item @emph{Specific names}:
2824 @multitable @columnfractions .24 .24 .24 .24
2825 @item Name            @tab Argument          @tab Return type       @tab Option
2826 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
2827 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
2828 @end multitable
2829 @end table
2830
2831
2832 @node REAL
2833 @section @code{REAL} --- Convert to real type
2834 @findex @code{REAL} intrinsic
2835 @findex @code{REALPART} intrinsic
2836 @cindex true values
2837
2838 @table @asis
2839 @item @emph{Description}:
2840 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type.  The
2841 @code{REALPART(X)} function is provided for compatibility with @command{g77},
2842 and its use is strongly discouraged.
2843
2844 @item @emph{Option}:
2845 f95, gnu
2846
2847 @item @emph{Class}:
2848 transformational function
2849
2850 @item @emph{Syntax}:
2851 @multitable @columnfractions .30 .80
2852 @item @code{X = REAL(X)}
2853 @item @code{X = REAL(X, KIND)}
2854 @item @code{X = REALPART(Z)}
2855 @end multitable
2856
2857 @item @emph{Arguments}:
2858 @multitable @columnfractions .15 .80
2859 @item @var{X} @tab shall be @code{INTEGER(*)}, @code{REAL(*)}, or
2860 @code{COMPLEX(*)}.
2861 @item @var{KIND}  @tab (Optional) @var{KIND} shall be a scalar integer.
2862 @end multitable
2863
2864 @item @emph{Return value}:
2865 These functions return the a @code{REAL(*)} variable or array under
2866 the following rules:
2867
2868 @table @asis
2869 @item (A)
2870 @code{REAL(X)} is converted to a default real type if @var{X} is an
2871 integer or real variable.
2872 @item (B)
2873 @code{REAL(X)} is converted to a real type with the kind type parameter
2874 of @var{X} if @var{X} is a complex variable.
2875 @item (C)
2876 @code{REAL(X, KIND)} is converted to a real type with kind type
2877 parameter @var{KIND} if @var{X} is a complex, integer, or real
2878 variable.
2879 @end table
2880
2881 @item @emph{Example}:
2882 @smallexample
2883 program test_real
2884   complex :: x = (1.0, 2.0)
2885   print *, real(x), real(x,8), realpart(x)
2886   end program test_real
2887 @end smallexample
2888 @end table
2889
2890
2891 @node SIN
2892 @section @code{SIN} --- Sine function
2893 @findex @code{SIN} intrinsic
2894 @findex @code{DSIN} intrinsic
2895 @findex @code{ZSIN} intrinsic
2896 @findex @code{CDSIN} intrinsic
2897 @cindex sine
2898
2899 @table @asis
2900 @item @emph{Description}:
2901 @code{SIN(X)} computes the sine of @var{X}.
2902
2903 @item @emph{Option}:
2904 f95, gnu
2905
2906 @item @emph{Class}:
2907 elemental function
2908
2909 @item @emph{Syntax}:
2910 @code{X = SIN(X)}
2911
2912 @item @emph{Arguments}:
2913 @multitable @columnfractions .15 .80
2914 @item @var{X} @tab The type shall be @code{REAL(*)} or
2915 @code{COMPLEX(*)}.
2916 @end multitable
2917
2918 @item @emph{Return value}:
2919 The return value has same type and king than @var{X}.
2920
2921 @item @emph{Example}:
2922 @smallexample
2923 program test_sin
2924   real :: x = 0.0
2925   x = sin(x)
2926 end program test_sin
2927 @end smallexample
2928
2929 @item @emph{Specific names}:
2930 @multitable @columnfractions .24 .24 .24 .24
2931 @item Name            @tab Argument          @tab Return type       @tab Option
2932 @item @code{DSIN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
2933 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
2934 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
2935 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
2936 @end multitable
2937 @end table
2938
2939
2940
2941 @node SINH
2942 @section @code{SINH} --- Hyperbolic sine function
2943 @findex @code{SINH} intrinsic
2944 @findex @code{DSINH} intrinsic
2945 @cindex hyperbolic sine
2946
2947 @table @asis
2948 @item @emph{Description}:
2949 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
2950
2951 @item @emph{Option}:
2952 f95, gnu
2953
2954 @item @emph{Class}:
2955 elemental function
2956
2957 @item @emph{Syntax}:
2958 @code{X = SINH(X)}
2959
2960 @item @emph{Arguments}:
2961 @multitable @columnfractions .15 .80
2962 @item @var{X} @tab The type shall be @code{REAL(*)}.
2963 @end multitable
2964
2965 @item @emph{Return value}:
2966 The return value is of type @code{REAL(*)}.
2967
2968 @item @emph{Example}:
2969 @smallexample
2970 program test_sinh
2971   real(8) :: x = - 1.0_8
2972   x = sinh(x)
2973 end program test_sinh
2974 @end smallexample
2975
2976 @item @emph{Specific names}:
2977 @multitable @columnfractions .24 .24 .24 .24
2978 @item Name            @tab Argument          @tab Return type       @tab Option
2979 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
2980 @end multitable
2981 @end table
2982
2983
2984
2985 @node SQRT
2986 @section @code{SQRT} --- Square-root function
2987 @findex @code{SQRT} intrinsic
2988 @findex @code{DSQRT} intrinsic
2989 @findex @code{CSQRT} intrinsic
2990 @findex @code{ZSQRT} intrinsic
2991 @findex @code{CDSQRT} intrinsic
2992 @cindex square-root
2993
2994 @table @asis
2995 @item @emph{Description}:
2996 @code{SQRT(X)} computes the square root of @var{X}.
2997
2998 @item @emph{Option}:
2999 f95, gnu
3000
3001 @item @emph{Class}:
3002 elemental function
3003
3004 @item @emph{Syntax}:
3005 @code{X = SQRT(X)}
3006
3007 @item @emph{Arguments}:
3008 @multitable @columnfractions .15 .80
3009 @item @var{X} @tab The type shall be @code{REAL(*)} or
3010 @code{COMPLEX(*)}.
3011 @end multitable
3012
3013 @item @emph{Return value}:
3014 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
3015 The kind type parameter is the same as @var{X}.
3016
3017 @item @emph{Example}:
3018 @smallexample
3019 program test_sqrt
3020   real(8) :: x = 2.0_8
3021   complex :: z = (1.0, 2.0)
3022   x = sqrt(x)
3023   z = sqrt(z)
3024 end program test_sqrt
3025 @end smallexample
3026
3027 @item @emph{Specific names}:
3028 @multitable @columnfractions .24 .24 .24 .24
3029 @item Name            @tab Argument          @tab Return type       @tab Option
3030 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
3031 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
3032 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
3033 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
3034 @end multitable
3035 @end table
3036
3037
3038
3039 @node TAN
3040 @section @code{TAN} --- Tangent function
3041 @findex @code{TAN} intrinsic
3042 @findex @code{DTAN} intrinsic
3043 @cindex tangent
3044
3045 @table @asis
3046 @item @emph{Description}:
3047 @code{TAN(X)} computes the tangent of @var{X}.
3048
3049 @item @emph{Option}:
3050 f95, gnu
3051
3052 @item @emph{Class}:
3053 elemental function
3054
3055 @item @emph{Syntax}:
3056 @code{X = TAN(X)}
3057
3058 @item @emph{Arguments}:
3059 @multitable @columnfractions .15 .80
3060 @item @var{X} @tab The type shall be @code{REAL(*)}.
3061 @end multitable
3062
3063 @item @emph{Return value}:
3064 The return value is of type @code{REAL(*)}.  The kind type parameter is
3065 the same as @var{X}.
3066
3067 @item @emph{Example}:
3068 @smallexample
3069 program test_tan
3070   real(8) :: x = 0.165_8
3071   x = tan(x)
3072 end program test_tan
3073 @end smallexample
3074
3075 @item @emph{Specific names}:
3076 @multitable @columnfractions .24 .24 .24 .24
3077 @item Name            @tab Argument          @tab Return type       @tab Option
3078 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
3079 @end multitable
3080 @end table
3081
3082
3083
3084 @node TANH
3085 @section @code{TANH} --- Hyperbolic tangent function
3086 @findex @code{TANH} intrinsic
3087 @findex @code{DTANH} intrinsic
3088 @cindex hyperbolic tangent
3089
3090 @table @asis
3091 @item @emph{Description}:
3092 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
3093
3094 @item @emph{Option}:
3095 f95, gnu
3096
3097 @item @emph{Class}:
3098 elemental function
3099
3100 @item @emph{Syntax}:
3101 @code{X = TANH(X)}
3102
3103 @item @emph{Arguments}:
3104 @multitable @columnfractions .15 .80
3105 @item @var{X} @tab The type shall be @code{REAL(*)}.
3106 @end multitable
3107
3108 @item @emph{Return value}:
3109 The return value is of type @code{REAL(*)} and lies in the range
3110 @math{ - 1 \leq tanh(x) \leq 1 }.
3111
3112 @item @emph{Example}:
3113 @smallexample
3114 program test_tanh
3115   real(8) :: x = 2.1_8
3116   x = tanh(x)
3117 end program test_tanh
3118 @end smallexample
3119
3120 @item @emph{Specific names}:
3121 @multitable @columnfractions .24 .24 .24 .24
3122 @item Name            @tab Argument          @tab Return type       @tab Option
3123 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
3124 @end multitable
3125 @end table
3126
3127
3128
3129 @comment sub   flush
3130 @comment
3131 @comment gen   fraction
3132 @comment
3133 @comment gen   fstat
3134 @comment sub   fstat
3135 @comment
3136 @comment sub   getarg
3137 @comment
3138 @comment gen   getcwd
3139 @comment sub   getcwd
3140 @comment
3141 @comment sub   getenv
3142 @comment
3143 @comment gen   getgid
3144 @comment
3145 @comment gen   getpid
3146 @comment
3147 @comment gen   getuid
3148 @comment
3149 @comment sub   get_command
3150 @comment
3151 @comment sub   get_command_argument
3152 @comment
3153 @comment sub   get_environment_variable
3154 @comment
3155 @comment gen   huge
3156 @comment
3157 @comment gen   iachar
3158 @comment
3159 @comment gen   iand
3160 @comment
3161 @comment gen   iargc
3162 @comment
3163 @comment gen   ibclr
3164 @comment
3165 @comment gen   ibits
3166 @comment
3167 @comment gen   ibset
3168 @comment
3169 @comment gen   ichar
3170 @comment
3171 @comment gen   ieor
3172 @comment
3173 @comment gen   index
3174 @comment
3175 @comment gen   int
3176 @comment       ifix
3177 @comment       idint
3178 @comment
3179 @comment gen   ior
3180 @comment
3181 @comment gen   irand
3182 @comment
3183 @comment gen   ishft
3184 @comment
3185 @comment gen   ishftc
3186 @comment
3187 @comment gen   kind
3188 @comment
3189 @comment gen   lbound
3190 @comment
3191 @comment gen   len
3192 @comment
3193 @comment gen   len_trim
3194 @comment
3195 @comment gen   lge
3196 @comment
3197 @comment gen   lgt
3198 @comment
3199 @comment gen   lle
3200 @comment
3201 @comment gen   llt
3202 @comment
3203 @comment gen   logical
3204 @comment
3205 @comment gen   matmul
3206 @comment
3207 @comment gen   max
3208 @comment       max0
3209 @comment       amax0
3210 @comment       amax1
3211 @comment       max1
3212 @comment       dmax1
3213 @comment
3214 @comment gen   maxexponent
3215 @comment
3216 @comment gen   maxloc
3217 @comment
3218 @comment gen   maxval
3219 @comment
3220 @comment gen   merge
3221 @comment
3222 @comment gen   min
3223 @comment       min0
3224 @comment       amin0
3225 @comment       amin1
3226 @comment       min1
3227 @comment       dmin1
3228 @comment
3229 @comment gen   minexponent
3230 @comment
3231 @comment gen   minloc
3232 @comment
3233 @comment gen   minval
3234 @comment
3235 @comment gen   mod
3236 @comment       amod
3237 @comment       dmod
3238 @comment
3239 @comment gen   modulo
3240 @comment
3241 @comment sub   mvbits
3242 @comment
3243 @comment gen   nearest
3244 @comment
3245 @comment gen   nint
3246 @comment       idnint
3247 @comment
3248 @comment gen   not
3249 @comment
3250 @comment gen   null
3251 @comment
3252 @comment gen   pack
3253 @comment
3254 @comment gen   precision
3255 @comment
3256 @comment gen   present
3257 @comment
3258 @comment gen   product
3259 @comment
3260 @comment gen   radix
3261 @comment
3262 @comment gen   rand
3263 @comment       ran
3264 @comment
3265 @comment sub   random_number
3266 @comment
3267 @comment sub   random_seed
3268 @comment
3269 @comment gen   range
3270 @comment
3271 @comment gen   real
3272 @comment       float
3273 @comment       sngl
3274 @comment
3275 @comment gen   repeat
3276 @comment
3277 @comment gen   reshape
3278 @comment
3279 @comment gen   rrspacing
3280 @comment
3281 @comment gen   scale
3282 @comment
3283 @comment gen   scan
3284 @comment
3285 @comment gen   second
3286 @comment sub   second
3287 @comment
3288 @comment gen   selected_int_kind
3289 @comment
3290 @comment gen   selected_real_kind
3291 @comment
3292 @comment gen   set_exponent
3293 @comment
3294 @comment gen   shape
3295 @comment
3296 @comment gen   sign
3297 @comment       isign
3298 @comment       dsign
3299 @comment
3300 @comment gen   size
3301 @comment
3302 @comment gen   spacing
3303 @comment
3304 @comment gen   spread
3305 @comment
3306 @comment sub   srand
3307 @comment
3308 @comment gen   stat
3309 @comment sub   stat
3310 @comment
3311 @comment gen   sum
3312 @comment
3313 @comment gen   system
3314 @comment sub   system
3315 @comment
3316 @comment sub system_clock
3317 @comment
3318 @comment gen   tiny
3319 @comment
3320 @comment gen   transfer
3321 @comment
3322 @comment gen   transpose
3323 @comment
3324 @comment gen   trim
3325 @comment
3326 @comment gen   ubound
3327 @comment
3328 @comment gen   umask
3329 @comment sub   umask
3330 @comment
3331 @comment gen   unlink
3332 @comment sub   unlink
3333 @comment
3334 @comment gen   unpack
3335 @comment
3336 @comment gen   verify
3337