This is the mail archive of the
fortran@gcc.gnu.org
mailing list for the GNU Fortran project.
[fortran, documentation, patch] document the last set of intrinsics
- From: Daniel Franke <franke dot daniel at gmail dot com>
- To: fortran at gcc dot gnu dot org
- Cc: gcc-patches at gcc dot gnu dot org
- Date: Sun, 22 Apr 2007 14:41:25 +0200
- Subject: [fortran, documentation, patch] document the last set of intrinsics
- Dkim-signature: a=rsa-sha1; c=relaxed/relaxed; d=gmail.com; s=beta; h=domainkey-signature:received:received:from:to:subject:date:user-agent:cc:mime-version:content-type:message-id; b=Z95Q+tZw1ugLlz0+CqiFiVUCN8eaaxs50pvGV7+N5RjQb4B6TPwfpjddHBAD8vmFLEzubLjX3Kr3kkshEyFykvQLnfTssWfXPwxXioaxI8N0Ff3mMcIPYAQzvku9FCW5sEKOVhBdvBAloLy/2zKsqn7eW8jetVRTQnl1XHIfU3k=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=beta; h=received:from:to:subject:date:user-agent:cc:mime-version:content-type:message-id; b=lo/0Fu33v930GnlaJLn6Ds4OxgJIoFkKZ/sUI5yU1cvZYkuhPm+gpbPsCi/8N1sXUvGxjPs+jTOi3axGSuwMUL/FtqFuVr5s7Rbkzt2aNcQL691vSxOn8L23TFAph0cTLhPy/LwX6q/wawf0GDY10fX0I9DuMSf3WuEAu9c7VV4=
This patch adds documentation for those intrinsics not documented yet.
2007-04-22 Daniel Franke <franke.daniel@gmail.com>
* intrinsic.texi (PRODUCT, RESHAPE, SPACING, SPREAD, SUM, SYSTEM_CLOCK,
TRANSFER, UNPACK): New.
(DATE_AND_TIME, CPU_TIME, RRSPACING): Added cross references.
Tested info and dvi targets on i686-pc-linux-gnu.
Ok for 4.2 and trunk?
Daniel
--- intrinsic.texi.11of18 2007-04-22 13:54:56.000000000 +0200
+++ intrinsic.texi 2007-04-22 14:20:14.000000000 +0200
@@ -2369,6 +2369,9 @@
print '("Time = ",f6.3," seconds.")',finish-start
end program test_cpu_time
@end smallexample
+
+@item @emph{See also}:
+@ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
@end table
@@ -2548,6 +2551,9 @@
print '(8i5))', values
end program test_time_and_date
@end smallexample
+
+@item @emph{See also}:
+@ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
@end table
@@ -7561,12 +7567,13 @@
@node PRODUCT
@section @code{PRODUCT} --- Product of array elements
@cindex @code{PRODUCT} intrinsic
-@cindex undocumented intrinsic
-
-Intrinsic implemented, documentation pending.
+@cindex array operation
@table @asis
@item @emph{Description}:
+Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
+the corresponding element in @var{MASK} is @code{TRUE}.
+
@item @emph{Standard}:
F95 and later
@@ -7574,10 +7581,37 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = PRODUCT(ARRAY[, MASK])}
+@code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
+@code{REAL(*)} or @code{COMPLEX(*)}.
+@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
+value in the range from 1 to n, where n equals the rank of @var{ARRAY}.
+@item @var{MASK} @tab Shall be of type @code{LOGICAL} and either be a
+scalar or an array of the same shape as @var{ARRAY}.
+@end multitable
+
@item @emph{Return value}:
+The result is of the same type as @var{ARRAY}.
+
+If @var{DIM} is absent, a scalar with the sum of all elements in @var{MASK}
+is returned. An array of rank n-1, where n equals the rank of @var{ARRAY},
+and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
+is returned otherwise.
+
+
@item @emph{Example}:
-@item @emph{Specific names}:
+@smallexample
+PROGRAM test_product
+ INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
+ print *, PRODUCT(x) ! all elements, product = 120
+ print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
@ref{SUM}
@end table
@@ -8037,6 +8071,8 @@
The value returned is equal to
@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
+@item @emph{See also}:
+@ref{SPACING}
@end table
@@ -8788,12 +8824,11 @@
@node SPACING
@section @code{SPACING} --- Smallest distance between two numbers of a given type
@cindex @code{SPACING} intrinsic
-@cindex undocumented intrinsic
-
-Intrinsic implemented, documentation pending.
@table @asis
@item @emph{Description}:
+Determines the smallest distance between two numbers of a given type.
+
@item @emph{Standard}:
F95 and later
@@ -8801,10 +8836,29 @@
Elemental function
@item @emph{Syntax}:
+@code{RESULT = SPACING(X)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{X} @tab Shall be of type @code{REAL(*)}.
+@end multitable
+
@item @emph{Return value}:
+The result is of the same type as the input argument @var{X}.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_spacing
+ INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
+ INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
+
+ WRITE(*,*) spacing(0.0_SGL) ! "1.1920929E-07" on i686
+ WRITE(*,*) spacing(0.0_DBL) ! "2.220446049250313E-016" on i686
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{RRSPACING}
@end table
@@ -8814,10 +8868,11 @@
@cindex @code{SPREAD} intrinsic
@cindex array manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
+dimension @var{DIM}.
+
@item @emph{Standard}:
F95 and later
@@ -8825,10 +8880,32 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{SOURCE} @tab Shall be a scalar or an array of any type and
+a rank less than seven.
+@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
+value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
+@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
+@end multitable
+
@item @emph{Return value}:
+The result is an array of the same type as @var{SOURCE} and has rank n+1
+where n equals the rank of @var{SOURCE}.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_spread
+ INTEGER :: a = 1, b(2) = (/ 1, 2 /)
+ WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
+ WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{UNPACK}
@end table
@@ -9018,12 +9095,13 @@
@node SUM
@section @code{SUM} --- Sum of array elements
@cindex @code{SUM} intrinsic
-@cindex array manipulation
-
-Intrinsic implemented, documentation pending.
+@cindex array operation
@table @asis
@item @emph{Description}:
+Adds up the elements of @var{ARRAY} along dimension @var{DIM} if
+the corresponding element in @var{MASK} is @code{TRUE}.
+
@item @emph{Standard}:
F95 and later
@@ -9031,9 +9109,36 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = SUM(ARRAY[, MASK])}
+@code{RESULT = SUM(ARRAY, DIM[, MASK])}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
+@code{REAL(*)} or @code{COMPLEX(*)}.
+@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
+value in the range from 1 to n, where n equals the rank of @var{ARRAY}.
+@item @var{MASK} @tab Shall be of type @code{LOGICAL} and either be a
+scalar or an array of the same shape as @var{ARRAY}.
+@end multitable
+
@item @emph{Return value}:
+The result is of the same type as @var{ARRAY}.
+
+If @var{DIM} is absent, a scalar with the sum of all elements in @var{MASK}
+is returned. An array of rank n-1, where n equals the rank of @var{ARRAY},
+and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
+is returned otherwise.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_sum
+ INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
+ print *, SUM(x) ! all elements, sum = 15
+ print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
@ref{PRODUCT}
@end table
@@ -9128,10 +9233,17 @@
@cindex time, current
@cindex current time
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Determines the @var{COUNT} of milliseconds of wall clock time since
+the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
+@var{COUNT_RATE} determines the number of clock ticks per second.
+@var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
+@command{gfortran}.
+
+If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
+@var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
+
@item @emph{Standard}:
F95 and later
@@ -9139,10 +9251,30 @@
Subroutine
@item @emph{Syntax}:
+@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE ,COUNT_MAX])}
+
@item @emph{Arguments}:
-@item @emph{Return value}:
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{COUNT} @tab (Optional) shall be a scalar of type default
+@code{INTEGER}.
+@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
+@code{INTEGER}.
+@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
+@code{INTEGER}.
+@end multitable
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_system_clock
+ INTEGER :: count, count_rate, count_max
+ CALL SYSTEM_CLOCK(count, count_rate, count_max)
+ WRITE(*,*) count, count_rate, count_max
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{DATE_AND_TIME}, @ref{CPU_TIME}
@end table
@@ -9359,12 +9491,14 @@
@node TRANSFER
@section @code{TRANSFER} --- Transfer bit patterns
@cindex @code{TRANSFER} intrinsic
-@cindex bit operations
-
-Intrinsic implemented, documentation pending.
+@cindex type cast
@table @asis
@item @emph{Description}:
+Interprets the bit pattern of @var{SOURCE} in as described by @var{MOLD}.
+
+This is also known as @emph{casting} one type to another.
+
@item @emph{Standard}:
F95 and later
@@ -9372,10 +9506,26 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{SOURCE} @tab Shall be a scalar or an array of any type.
+@item @var{MOLD} @tab Shall be a scalar or an array of any type.
+@item @var{SIZE} @tab Shall be a scalar and of type @code{INTEGER}.
+@end multitable
+
@item @emph{Return value}:
+The result has the same type as @var{MOLD} with the bit level
+representation of @var{SOURCE}.
+
@item @emph{Example}:
-@item @emph{See also}:
+@smallexample
+PROGRAM test_transfer
+ integer :: x = 2143289344
+ print *, transfer(x, 1.0) ! prints "NaN" on i686
+END PROGRAM
+@end smallexample
@end table
@@ -9612,10 +9762,10 @@
@cindex @code{UNPACK} intrinsic
@cindex array manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Store the elements of @var{VECTOR} in an array of higher rank.
+
@item @emph{Standard}:
F95 and later
@@ -9623,12 +9773,34 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{VECTOR} @tab Shall be an array of any type and rank one. It
+shall have at least as many elements as @var{MASK} has @code{TRUE} values.
+@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
+@item @var{FIELD} @tab Shall be of the sam type as @var{VECTOR} and have
+the same shape as @var{MASK}.
+@end multitable
+
@item @emph{Return value}:
+The resulting array correspond to @var{FIELD} with @code{TRUE} elements
+of @var{MASK} replaced by values from @var{VECTOR}.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_unpack
+ integer :: vector(2) = (/1,1/)
+ logical :: mask(2,2) = reshape((/ .TRUE., .FALSE., .FALSE., .TRUE. /), (/2,2/))
+ integer :: field(2,2) = 0, unity
+
+ unity = unpack(vector, mask, field) ! result: unity matrix
+END PROGRAM
+@end smallexample
@item @emph{See also}:
-@ref{PACK}
+@ref{PACK}, @ref{SPREAD}
@end table