From f60d648137b2d2cda1c598996b9598d559715117 Mon Sep 17 00:00:00 2001 From: Jerry DeLisle Date: Sat, 2 Jul 2005 03:17:55 +0000 Subject: [PATCH] intrinsic.texi: Add documentaion for eoshift, epsilon, etime, and exit. 2005-07-01 Jerry DeLisle * intrinsic.texi: Add documentaion for eoshift, epsilon, etime, and exit. Fixed alignment of text for dtime syntax. Fixed a few line lengths. From-SVN: r101530 --- gcc/fortran/ChangeLog | 7 ++ gcc/fortran/intrinsic.texi | 251 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 242 insertions(+), 16 deletions(-) diff --git a/gcc/fortran/ChangeLog b/gcc/fortran/ChangeLog index 617747d..2e9053e 100644 --- a/gcc/fortran/ChangeLog +++ b/gcc/fortran/ChangeLog @@ -1,3 +1,10 @@ +2005-07-01 Jerry DeLisle + + * gfortran.texi: Fix typos and grammar. + * invoke.texi: Fix typos and grammar. + * intrinsic.texi: Add documentaion for eoshift, epsilon, etime, and exit. + Fixed alignment of text for dtime syntax. Fixed a few line lengths. + 2005-06-25 Jakub Jelinek * trans-stmt.c (gfc_trans_forall_1): Prefer to use smaller logical diff --git a/gcc/fortran/intrinsic.texi b/gcc/fortran/intrinsic.texi index a524885..72fb77b 100644 --- a/gcc/fortran/intrinsic.texi +++ b/gcc/fortran/intrinsic.texi @@ -77,8 +77,12 @@ and editing. All contributions and corrections are strongly encouraged. * @code{DPROD}: DPROD, Double product function * @code{DREAL}: DREAL, Double real part function * @code{DTIME}: DTIME, Execution time subroutine (or function) +* @code{EOSHIFT}: EOSHIFT, End-off shift function +* @code{EPSILON}: EPSILON, Epsilon function * @code{ERF}: ERF, Error function * @code{ERFC}: ERFC, Complementary error function +* @code{ETIME}: ETIME, Execution time subroutine (or function) +* @code{EXIT}: EXIT, Exit the program with status. * @code{EXP}: EXP, Cosine function * @code{LOG}: LOG, Logarithm function * @code{LOG10}: LOG10, Base 10 logarithm function @@ -665,8 +669,8 @@ end program test_anint @table @asis @item @emph{Description}: -@code{ANY(MASK [, DIM])} determines if any of the values in the logical array @var{MASK} -along dimension @var{DIM} are @code{.TRUE.}. +@code{ANY(MASK [, DIM])} determines if any of the values in the logical array +@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. @item @emph{Option}: f95, gnu @@ -1225,7 +1229,8 @@ end program test_besyn @table @asis @item @emph{Description}: -@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) represented by the type of @var{I}. +@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) +represented by the type of @var{I}. @item @emph{Option}: f95, gnu @@ -1264,7 +1269,8 @@ end program test_bit_size @table @asis @item @emph{Description}: -@code{BTEST(I,POS)} returns logical .TRUE. if the bit at @var{POS} in @var{I} is set. +@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} +in @var{I} is set. @item @emph{Option}: f95, gnu @@ -1964,7 +1970,6 @@ 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) @@ -2166,9 +2171,11 @@ end program test_dreal @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)}. +@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. +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 @@ -2194,8 +2201,10 @@ gnu subroutine @item @emph{Syntax}: -@code{CALL DTIME(TARRAY, RESULT)} -@code{RESULT = DTIME(TARRAY)}, (not recommended) +@multitable @columnfractions .80 +@item @code{CALL DTIME(TARRAY, RESULT)}. +@item @code{RESULT = DTIME(TARRAY)}, (not recommended). +@end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .80 @@ -2229,6 +2238,110 @@ end program test_dtime +@node EOSHIFT +@section @code{EOSHIFT} --- End-off shift function +@findex @code{EOSHIFT} intrinsic +@cindex eoshift intrinsic + +@table @asis +@item @emph{Description}: +@code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on +elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is +omitted it is taken to be @code{1}. @var{DIM} is a scaler of type +@code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the +rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of +@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, +then all complete rank one sections of @var{ARRAY} along the given dimension are +shifted. Elements shifted out one end of each rank one section are dropped. If +@var{BOUNDARY} is present then the cooresponding value of from @var{BOUNDARY} +is copied back in the other end. If @var{BOUNDARY} is not present then the +following are copied in depending on the type of @var{ARRAY}. + +@multitable @columnfractions .15 .80 +@item @emph{Array Type} @tab @emph{Boundary Value} +@item Numeric @tab 0 of the type and kind of @var{ARRAY}. +@item Logical @tab @code{.FALSE.}. +@item Character(@var{len}) @tab @var{len} blanks. +@end multitable + +@item @emph{Option}: +f95, gnu + +@item @emph{Class}: +transformational function + +@item @emph{Syntax}: +@code{A = EOSHIFT(A, SHIFT[,BOUNDARY, DIM])} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .80 +@item @var{ARRAY} @tab May be any type, not scaler. +@item @var{SHIFT} @tab The type shall be @code{INTEGER}. +@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. +@item @var{DIM} @tab The type shall be @code{INTEGER}. +@end multitable + +@item @emph{Return value}: +Returns an array of same type and rank as the @var{ARRAY} argument. + +@item @emph{Example}: +@smallexample +program test_eoshift + integer, dimension(3,3) :: a + a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) + print '(3i3)', a(1,:) + print '(3i3)', a(2,:) + print '(3i3)', a(3,:) + a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) + print * + print '(3i3)', a(1,:) + print '(3i3)', a(2,:) + print '(3i3)', a(3,:) +end program test_eoshift +@end smallexample +@end table + + + +@node EPSILON +@section @code{EPSILON} --- Epsilon function +@findex @code{EPSILON} intrinsic +@cindex epsilon, significant + +@table @asis +@item @emph{Description}: +@code{EPSILON(X)} returns a nearly negligible number relative to @code{1}. + +@item @emph{Option}: +f95, gnu + +@item @emph{Class}: +inquiry function + +@item @emph{Syntax}: +@code{C = EPSILON(X)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .80 +@item @var{X} @tab The type shall be @code{REAL(*)}. +@end multitable + +@item @emph{Return value}: +The return value is of same type as the argument. + +@item @emph{Example}: +@smallexample +program test_epsilon + real :: x = 3.143 + real(8) :: y = 2.33 + print *, EPSILON(x) + print *, EPSILON(y) +end program test_epsilon +@end smallexample +@end table + + + @node ERF @section @code{ERF} --- Error function @findex @code{ERF} intrinsic @@ -2317,6 +2430,119 @@ end program test_erfc +@node ETIME +@section @code{ETIME} --- Execution time subroutine (or function) +@findex @code{ETIME} intrinsic +@cindex ETIME subroutine + +@table @asis +@item @emph{Description}: +@code{ETIME(TARRAY, RESULT)} 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)}. + +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{ETIME} 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}: +@multitable @columnfractions .8 +@item @code{CALL ETIME(TARRAY, RESULT)}. +@item @code{RESULT = ETIME(TARRAY)}, (not recommended). +@end multitable + +@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_etime + integer(8) :: i, j + real, dimension(2) :: tarray + real :: result + call ETIME(tarray, result) + print *, result + print *, tarray(1) + print *, tarray(2) + do i=1,100000000 ! Just a delay + j = i * i - i + end do + call ETIME(tarray, result) + print *, result + print *, tarray(1) + print *, tarray(2) +end program test_etime +@end smallexample +@end table + + + +@node EXIT +@section @code{EXIT} --- Exit the program with status. +@findex @code{EXIT} +@cindex exit + +@table @asis +@item @emph{Description}: +@code{EXIT} causes immediate termination of the program with status. If status +is omitted it returns the connonical @emph{success} for the system. All Fortran +I/O units are closed. + +@item @emph{Option}: +gnu + +@item @emph{Class}: +non-elemental subroutine + +@item @emph{Syntax}: +@code{CALL EXIT([STATUS])} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .80 +@item @var{STATUS} @tab The type of the argument shall be @code{INTEGER(*)}. +@end multitable + +@item @emph{Return value}: +@code{STATUS} is passed to the parent process on exit. + +@item @emph{Example}: +@smallexample +program test_exit + integer :: STATUS = 0 + print *, 'This program is going to exit.' + call EXIT(STATUS) +end program test_exit +@end smallexample +@end table + + + @node EXP @section @code{EXP} --- Exponential function @findex @code{EXP} intrinsic @@ -2709,13 +2935,6 @@ end program test_tanh -@comment gen eoshift -@comment -@comment gen epsilon -@comment -@comment gen etime -@comment sub etime -@comment @comment sub exit @comment @comment gen exponent -- 2.7.4