intrinsic.texi: Add documentation for dcmplx...

2005-06-03  Jerry DeLisle <jvdelisle@verizon.net>

	* intrinsic.texi: Add documentation for	dcmplx, digits,
	dim, idim, ddim, dot_product, dprod, dreal, and dtime.

From-SVN: r100697

gcc/fortran/ChangeLog

@@ -1,3 +1,8 @@
+2005-06-03  Jerry DeLisle <jvdelisle@verizon.net>
+
+	* intrinsic.texi: Add documentation for	dcmplx, digits,
+	dim, idim, ddim, dot_product, dprod, dreal, and dtime.
+
 2005-06-05  Tobias Schl"uter  <tobias.schlueter@physik.uni-muenchen.de>
 
 	PR fortran/21912

gcc/fortran/intrinsic.texi

@@ -66,10 +66,17 @@ and editing.  All contributions and corrections are strongly encouraged.
 * @code{COSH}:          COSH,      Hyperbolic cosine function
 * @code{COUNT}:         COUNT,     Count occurences of .TRUE. in an array
 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
-* @code{CSHIFT}:        CSHIFT,    Circular array shift
+* @code{CSHIFT}:        CSHIFT,    Circular array shift function
 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
-* @code{DBLE}:          DBLE,      Double precision conversion
+* @code{DBLE}:          DBLE,      Double precision conversion function
-* @code{DFLOAT}:        DFLOAT,    Double precision conversion
+* @code{DCMPLX}:        DCMPLX,    Double complex conversion function
+* @code{DFLOAT}:        DFLOAT,    Double precision conversion function
+* @code{DIGITS}:        DIGITS,    Significant digits function
+* @code{DIM}:           DIM,       Dim function
+* @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
+* @code{DPROD}:         DPROD,     Double product function
+* @code{DREAL}:         DREAL,     Double real part function
+* @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 * @code{ERF}:           ERF,       Error function
 * @code{ERFC}:          ERFC,      Complementary error function
 * @code{EXP}:           EXP,       Cosine function
@@ -98,7 +105,7 @@ the Fortran 95 standard.  Gfortran defines the default integer type and
 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 respectively.  The standard mandates that both data types shall have
 another kind, which have more precision.  On typical target architectures
-supports by @command{gfortran}, this kind type parameter is @code{KIND=8}.
+supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 In the description of generic intrinsic procedures, the kind type parameter
 will be specified by @code{KIND=*}, and in the description of specific
@@ -113,7 +120,7 @@ and denotes such arguments by square brackets.
 @command{Gfortran} offers the @option{-std=f95} and @option{-std=gnu} options,
 which can be used to restrict the set of intrinsic procedures to a 
 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
-option, and so all intrinsic procedures describe here are accepted.  There
+option, and so all intrinsic procedures described here are accepted.  There
 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 implemented both a function and a subroutine.  Both classes 
 have been implemented in @command{gfortran} for backwards compatibility
@@ -449,7 +456,7 @@ f95, gnu
 elemental function
 
 @item @emph{Syntax}:
-@code{X = AINT(X)} @*
+@code{X = AINT(X)} 
 @code{X = AINT(X, KIND)}
 
 @item @emph{Arguments}:
@@ -506,7 +513,7 @@ f95, gnu
 transformational function
 
 @item @emph{Syntax}:
-@code{L = ALL(MASK)} @*
+@code{L = ALL(MASK)} 
 @code{L = ALL(MASK, DIM)}
 
 @item @emph{Arguments}:
@@ -613,7 +620,7 @@ f95, gnu
 elemental function
 
 @item @emph{Syntax}:
-@code{X = ANINT(X)} @*
+@code{X = ANINT(X)}
 @code{X = ANINT(X, KIND)}
 
 @item @emph{Arguments}:
@@ -658,8 +665,8 @@ end program test_anint
 
 @table @asis
 @item @emph{Description}:
-@code{ANY(MASK [, DIM])} determines if any of the values is true in @var{MASK}
+@code{ANY(MASK [, DIM])} determines if any of the values in the logical array @var{MASK}
-in the array along dimension @var{DIM}.
+along dimension @var{DIM} are @code{.TRUE.}.
 
 @item @emph{Option}:
 f95, gnu
@@ -668,7 +675,7 @@ f95, gnu
 transformational function
 
 @item @emph{Syntax}:
-@code{L = ANY(MASK)} @*
+@code{L = ANY(MASK)} 
 @code{L = ANY(MASK, DIM)}
 
 @item @emph{Arguments}:
@@ -782,7 +789,7 @@ f95, gnu
 inquiry function
 
 @item @emph{Syntax}:
-@code{L = ASSOCIATED(PTR)} @*
+@code{L = ASSOCIATED(PTR)} 
 @code{L = ASSOCIATED(PTR [, TGT])}
 
 @item @emph{Arguments}:
@@ -1771,7 +1778,7 @@ Unavailable time and date parameters return blanks.
 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
 
 @multitable @columnfractions .15 .30 .60
-@item @tab @code{VALUE(1)}: @tab The year	
+@item @tab @code{VALUE(1)}: @tab The year
 @item @tab @code{VALUE(2)}: @tab The month
 @item @tab @code{VALUE(3)}: @tab The day of the month
 @item @tab @code{VAlUE(4)}: @tab Time difference with UTC in minutes
@@ -1790,13 +1797,12 @@ subroutine
 @item @emph{Syntax}:
 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
 
-
 @item @emph{Arguments}:
 @multitable @columnfractions .15 .80
 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
 @item @var{TIME}  @tab (OPtional) The type shall be @code{CHARACTER(10)} or larger.
 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
-@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}
+@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
 @end multitable
 
 @item @emph{Return value}:
@@ -1863,6 +1869,54 @@ end program test_dble
 
 
 
+@node DCMPLX
+@section @code{DCMPLX} --- Double complex conversion function
+@findex @code{DCMPLX} intrinsic
+@cindex DCMPLX
+
+@table @asis
+@item @emph{Description}:
+@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
+converted to the real component.  If @var{Y} is present it is converted to the
+imaginary component.  If @var{Y} is not present then the imaginary component is
+set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
+
+@item @emph{Option}:
+f95, gnu
+
+@item @emph{Class}:
+elemental function
+
+@item @emph{Syntax}:
+@code{C = DCMPLX(X)}
+@code{C = DCMPLX(X,Y)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.
+@item @var{Y} @tab Optional if @var{X} is not @code{COMPLEX(*)}. May be @code{INTEGER(*)} or @code{REAL(*)}. 
+@end multitable
+
+@item @emph{Return value}:
+The return value is of type @code{COMPLEX(8)}
+
+@item @emph{Example}:
+@smallexample
+program test_dcmplx
+    integer :: i = 42
+    real :: x = 3.14
+    complex :: z
+    z = cmplx(i, x)
+    print *, dcmplx(i)
+    print *, dcmplx(x)
+    print *, dcmplx(z)
+    print *, dcmplx(x,i)
+end program test_dcmplx
+@end smallexample
+@end table
+
+
+
 @node DFLOAT
 @section @code{DFLOAT} --- Double conversion function 
 @findex @code{DFLOAT} intrinsic
@@ -1876,6 +1930,305 @@ end program test_dble
 
 
 
+@node DIGITS
+@section @code{DIGITS} --- Significant digits function
+@findex @code{DIGITS} intrinsic
+@cindex digits, significant
+
+@table @asis
+@item @emph{Description}:
+@code{DIGITS(X)} returns the number of significant digits of the internal model
+representation of @var{X}.  For example, on a system using a 32-bit
+floating point representation, a default real number would likely return 24.
+
+@item @emph{Option}:
+f95, gnu
+
+@item @emph{Class}:
+inquiry function
+
+@item @emph{Syntax}:
+@code{C = DIGITS(X)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
+@end multitable
+
+@item @emph{Return value}:
+The return value is of type @code{INTEGER}.
+
+@item @emph{Example}:
+@smallexample
+program test_digits
+    integer :: i = 12345
+    real :: x = 3.143
+    real(8) :: y = 2.33
+    complex :: z = (23.0,45.6)
+    print *, digits(i)
+    print *, digits(x)
+    print *, digits(y)
+end program test_digits
+@end smallexample
+@end table
+
+
+
+@node DIM
+@section @code{DIM} --- Dim function
+@findex @code{DIM} intrinsic
+@findex @code{IDIM} intrinsic
+@findex @code{DDIM} intrinsic
+@cindex dim
+
+@table @asis
+@item @emph{Description}:
+@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
+otherwise returns zero.
+
+@item @emph{Option}:
+f95, gnu
+
+@item @emph{Class}:
+elemental function
+
+@item @emph{Syntax}:
+@code{X = DIM(X,Y)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
+@item @var{Y} @tab The type shall be the same type and kind as @var{X}.
+@end multitable
+
+@item @emph{Return value}:
+The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
+
+@item @emph{Example}:
+@smallexample
+program test_dim
+    integer :: i
+    real(8) :: x
+    i = dim(4, 15)
+    x = dim(4.345_8, 2.111_8)
+    print *, i
+    print *, x
+end program test_dim
+@end smallexample
+
+@item @emph{Specific names}:
+@multitable @columnfractions .24 .24 .24 .24
+@item Name            @tab Argument          @tab Return type       @tab Option
+@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab gnu
+@item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}  @tab @code{REAL(8)} @tab gnu
+@end multitable
+@end table
+
+
+
+@node DOT_PRODUCT
+@section @code{DOT_PRODUCT} --- Dot product function
+@findex @code{DOT_PRODUCT} intrinsic
+@cindex Dot product
+
+@table @asis
+@item @emph{Description}:
+@code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
+@var{X} and @var{Y}.  The two vectors may be either numeric or logical
+and must be arrays of rank one and of equal size. If the vectors are
+@code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
+vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the 
+vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
+
+@item @emph{Option}:
+f95
+
+@item @emph{Class}:
+transformational function
+
+@item @emph{Syntax}:
+@code{S = DOT_PRODUCT(X,Y)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
+@item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
+@end multitable
+
+@item @emph{Return value}:
+If the arguments are numeric, the return value is a scaler of numeric type,
+@code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.  If the arguments are
+@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
+
+@item @emph{Example}:
+@smallexample
+program test_dot_prod
+    integer, dimension(3) :: a, b
+    a = (/ 1, 2, 3 /)
+    b = (/ 4, 5, 6 /)
+    print '(3i3)', a
+    print *
+    print '(3i3)', b
+    print *
+    print *, dot_product(a,b)
+end program test_dot_prod
+@end smallexample
+@end table
+
+
+
+@node DPROD
+@section @code{DPROD} --- Double product function
+@findex @code{DPROD} intrinsic
+@cindex Double product
+
+@table @asis
+@item @emph{Description}:
+@code{DPROD(X,Y)} returns the product @code{X*Y}.
+
+@item @emph{Option}:
+f95, gnu
+
+@item @emph{Class}:
+elemental function
+
+@item @emph{Syntax}:
+@code{D = DPROD(X,Y)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{X} @tab The type shall be @code{REAL}.
+@item @var{Y} @tab The type shall be @code{REAL}.
+@end multitable
+
+@item @emph{Return value}:
+The return value is of type @code{REAL(8)}.
+
+@item @emph{Example}:
+@smallexample
+program test_dprod
+    integer :: i
+    real :: x = 5.2
+    real :: y = 2.3
+    real(8) :: d
+    d = dprod(x,y)
+    print *, d
+end program test_dprod
+@end smallexample
+@end table
+
+
+
+@node DREAL
+@section @code{DREAL} --- Double real part function
+@findex @code{DREAL} intrinsic
+@cindex Double real part
+
+@table @asis
+@item @emph{Description}:
+@code{DREAL(Z)} returns the real part of complex variable @var{Z}.
+
+@item @emph{Option}:
+gnu
+
+@item @emph{Class}:
+elemental function
+
+@item @emph{Syntax}:
+@code{D = DREAL(Z)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
+@end multitable
+
+@item @emph{Return value}:
+The return value is of type @code{REAL(8)}.
+
+@item @emph{Example}:
+@smallexample
+program test_dreal
+    complex(8) :: z = (1.3_8,7.2_8)
+    print *, dreal(z)
+end program test_dreal
+@end smallexample
+@end table
+
+
+
+@node DTIME
+@section @code{DTIME} --- Execution time subroutine (or function)
+@findex @code{DTIME} intrinsic
+@cindex dtime subroutine 
+
+@table @asis
+@item @emph{Description}:
+@code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
+since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
+returns the user and system components of this time in @code{TARRAY(1)} and
+@code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
+
+Subsequent invocations of @code{DTIME} return values accumulated since the previous invocation.
+
+On some systems, the underlying timings are represented using types with
+sufficiently small limits that overflows (wraparounds) are possible, such as
+32-bit types. Therefore, the values returned by this intrinsic might be, or
+become, negative, or numerically less than previous values, during a single
+run of the compiled program.
+
+If @code{DTIME} is invoked as a function, it can not be invoked as a
+subroutine, and vice versa.
+
+@var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
+
+@multitable @columnfractions .15 .30 .60
+@item @tab @code{TARRAY(1)}: @tab User time in seconds.
+@item @tab @code{TARRAY(2)}: @tab System time in seconds.
+@item @tab @code{RESULT}: @tab Run time since start in seconds.
+@end multitable
+
+@item @emph{Option}:
+gnu
+
+@item @emph{Class}:
+subroutine
+
+@item @emph{Syntax}:
+@code{CALL DTIME(TARRAY, RESULT)}
+@code{RESULT = DTIME(TARRAY)}, (not recommended)
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .80
+@item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
+@item @var{RESULT}@tab The type shall be @code{REAL}.
+@end multitable
+
+@item @emph{Return value}:
+Elapsed time in seconds since the start of program execution.
+
+@item @emph{Example}:
+@smallexample
+program test_dtime
+    integer(8) :: i, j
+    real, dimension(2) :: tarray
+    real :: result
+    call dtime(tarray, result)
+    print *, result
+    print *, tarray(1)
+    print *, tarray(2)   
+    do i=1,100000000    ! Just a delay
+        j = i * i - i
+    end do
+    call dtime(tarray, result)
+    print *, result
+    print *, tarray(1)
+    print *, tarray(2)
+end program test_dtime
+@end smallexample
+@end table
+
+
+
 @node ERF
 @section @code{ERF} --- Error function 
 @findex @code{ERF} intrinsic
@@ -2356,22 +2709,6 @@ end program test_tanh
 
 
 
-@comment gen   dcmplx
-@comment 
-@comment gen   digits
-@comment 
-@comment gen   dim
-@comment       idim
-@comment       ddim
-@comment 
-@comment gen   dot_product
-@comment 
-@comment gen   dprod
-@comment 
-@comment gen   dreal 
-@comment 
-@comment sub   dtime
-@comment 
 @comment gen   eoshift
 @comment 
 @comment gen   epsilon