This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [fortran, documentation, patch] document the last set of intrinsics


> > 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.

Here's an updated patch.
At first, comments on FX' review, further down comments on Brook's.

Please also note the up-until-now missing node for RESHAPE.

If this is ok, I'll commit it tommorow evening along with the example-fixes 
and the command-line index. Afterwards, the whole enchilada will be 
backported to 4.2 - uff. 

Good night.
	Daniel


On Monday 23 April 2007 23:57:23 FX Coudert wrote:

> > +@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}.
>
> What about "with a value in the range from 1 to the rank of @var
> {ARRAY}"? It's simpler.

It's a phrase used more often throughout the document. Admitted, the phrase is 
used in many variation. At some time, these things need to be unified.


> > +If @var{DIM} is absent, a scalar with the sum of all elements in
> > @var{MASK}
> > +is returned.
>
> "product of all elements in @var{ARRAY}", instead? I mean, product
> instead of sum, and ARRAY instead of MASK

Done.

> > @section @code{SUM} --- Sum of array elements
>
> Same remarks as PRODUCT.

Done. 


> > +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 COUNT_RATE and COUNT_MAX are constant across architectures (for
> gfortran), maybe we could include their value in the doc?

IMO, this encourages people to take them as granted and hardcode something. 
Remember your recent statements about magic numbers on the ML :)


> Also, nothing here says that all these arguments are intent(out). 

Now reads:
@item @var{COUNT}      @tab (Optional) shall be a scalar of type default 
@code{INTEGER} with @code{INTENT(OUT)}.


> > +This is also known as @emph{casting} one type to another.
>
> Here, or in a note, I think we should say clearly that it's the
> Fortran 95 way of doing what people often achieve by invalid uses of
> equivalence; it might even be worth putting an example about that.

Any examples? As said, my own insight in TRANSFER is limited at best.


> > +The resulting array correspond to @var{FIELD} with @code{TRUE}
> > elements
> > +of @var{MASK} replaced by values from @var{VECTOR}.
>
> "corresponds", with a final s.

Done.



On Tuesday 24 April 2007 10:46:05 Brooks Moses wrote:

> >  @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}.
>
> The last two of those need to have "(Optional)" added.

Done.


> > +@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.
>
> I think that would be a little clearer as "Otherwise, an array of ... is
> returned."

Ok, if you say so ... done.


> >  @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
>
> These lines look somewhat long -- can you confirm that they don't
> produce overlength line errors in the .dvi output?

Confirmed. No overfull boxes. Nevertheless, I removed some whitespaces just in 
case.



> > @@ -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.
>
> This should be something like "the distance between the argument and the
> nearest adjacent number of the same type", I think.  The idea that it's
> the smallest distance near the argument, not the smallest distance
> anywhere, needs to be in there somewhere.

According to your suggestion, this now reads:

@item @emph{Description}:
Determines the distance between the argument @var{X} and the nearest 
adjacent number of the same type.


> >  @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
>
> According to the F2003 standard, SPACING(0_KIND) returns the same thing
> as TINY(0_KIND), so if those are actual results, we've got a bug.
> Perhaps the arguments should be 1.0 rather than 0.0?

You are right. I managed to mix things up here. Considerably.
Thanks for catching it!


> > @@ -9018,12 +9095,13 @@
> >  @node SUM
> >  @item @emph{Description}:
> > +Adds up the elements of @var{ARRAY} along dimension @var{DIM} if
> > +the corresponding element in @var{MASK} is @code{TRUE}.
>
> "Adds the elements".  (The "adds up" phrasing is a bit of an informal
> colloquialism.)

Done.


> >  @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
>
> DIM and MASK need "(Optional)".

Where can I get a large sign: "Copy-paste is Evil"?
Done.


> > @@ -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}.
>
> I think that's formally "the Unix Epoch", as there are other epochs.

$> man 2 time
"time() returns the time since the Epoch (00:00:00 UTC, January 1, 1970), 
measured in seconds."


> >  @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
>
> Looks like from check.c and iresolve.c that these can be of any integer
> kind, not just the default.


F95, section 13.14.106:
"COUNT (optional) shall be scalar and of type default integer."

This section now reads (see also above):
@item @var{COUNT}      @tab (Optional) shall be a scalar of type default 
@code{INTEGER} with @code{INTENT(OUT)}.




> > @@ -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}.
>
> "in as described" is missing a word.  Though maybe phrase it as "of
> @var{SOURCE} as a variable of the same type and type parameters as
> @var{MOLD}"?

Sounds good to me. Taken.


> >  @item @emph{Return value}:
> > +The result has the same type as @var{MOLD} with the bit level
> > +representation of @var{SOURCE}.
>
> I think this also needs a sentence of explanation about when the result
> is an array or a scalar, and how the length of the result is calculated.

This is TRANSFER again. I'm not very happy with it. As indicated before, my 
understanding of TRANSFER is approx. nil. Could anyone else step up to this?


> >  @item @emph{Return value}:
> > +The resulting array correspond to @var{FIELD} with @code{TRUE} elements
> > +of @var{MASK} replaced by values from @var{VECTOR}.
>
> I think that should have "in array element order" added to the end of
> the sentence.

@item @emph{Return value}:
The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
of @var{MASK} replaced by values from @var{VECTOR} in array element order.


> >  @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
>
> That's definitely an over-long line, and should be wrapped somehow.

Preferable, with a better example. Until someone finds one, this may do:

PROGRAM test_unpack
  integer :: vector(2)  = (/1,1/)
  logical :: mask(2,2)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
  integer :: field(2,2) = 0, unity(2,2)

  ! result: unity matrix
  unity = unpack(vector, reshape(mask, (/2,2/), field)
END PROGRAM



Last but not least, the really last entry, that was missing up until now 
(although advertised in the ChangeLog entry):

@node RESHAPE
@section @code{RESHAPE} --- Function to reshape an array
@cindex @code{RESHAPE} intrinsic
@cindex array manipulation

@table @asis
@item @emph{Description}:
Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
the new array may be padded with elements from @var{PAD} or permuted
as defined by @var{ORDER}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SOURCE} @tab Shall be an array of any type.
@item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an 
array of rank one. Its values must be positive or zero.
@item @var{PAD}    @tab (Optional) shall be an array of the same 
type as @var{SOURCE}.
@item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
and an array of the same shape as @var{SHAPE}. Its values shall
be a permutation of the numbers from 1 to n, where n is the size of 
@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
be assumed.
@end multitable

@item @emph{Return value}:
The result is an array of shape @var{SHAPE} with the same type as 
@var{SOURCE}. 

@item @emph{Example}:
@smallexample
PROGRAM test_reshape
  INTEGER, DIMENSION(2) :: x
  WRITE(*,*) SHAPE(x)
  WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{SHAPE}
@end table

Index: intrinsic.texi
===================================================================
--- intrinsic.texi	(revision 124200)
+++ intrinsic.texi	(working copy)
@@ -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
 
 
@@ -7562,12 +7568,13 @@
 @node PRODUCT
 @section @code{PRODUCT} --- Product of array elements
 @cindex @code{PRODUCT} intrinsic
-@cindex undocumented intrinsic 
+@cindex array operation
 
-Intrinsic implemented, documentation pending.
-
 @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
 
@@ -7575,10 +7582,38 @@
 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 (Optional) 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 (Optional) 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 product of all elements in 
+@var{ARRAY} is returned. Otherwise, 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.
+
+
 @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
@@ -7990,10 +8025,12 @@
 @cindex @code{RESHAPE} intrinsic
 @cindex array manipulation
 
-Intrinsic implemented, documentation pending.
-
 @table @asis
 @item @emph{Description}:
+Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
+the new array may be padded with elements from @var{PAD} or permuted
+as defined by @var{ORDER}.
+
 @item @emph{Standard}:
 F95 and later
 
@@ -8001,11 +8038,37 @@
 Transformational function
 
 @item @emph{Syntax}:
+@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
+
 @item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{SOURCE} @tab Shall be an array of any type.
+@item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an 
+array of rank one. Its values must be positive or zero.
+@item @var{PAD}    @tab (Optional) shall be an array of the same 
+type as @var{SOURCE}.
+@item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
+and an array of the same shape as @var{SHAPE}. Its values shall
+be a permutation of the numbers from 1 to n, where n is the size of 
+@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
+be assumed.
+@end multitable
+
 @item @emph{Return value}:
+The result is an array of shape @var{SHAPE} with the same type as 
+@var{SOURCE}. 
+
 @item @emph{Example}:
+@smallexample
+PROGRAM test_reshape
+  INTEGER, DIMENSION(4) :: x
+  WRITE(*,*) SHAPE(x)                       ! prints "4"
+  WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
+END PROGRAM
+@end smallexample
+
 @item @emph{See also}:
-@ref{SHAPE}, @ref{SIZE}
+@ref{SHAPE}
 @end table
 
 
@@ -8038,6 +8101,8 @@
 The value returned is equal to
 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
 
+@item @emph{See also}:
+@ref{SPACING}
 @end table
 
 
@@ -8444,7 +8509,7 @@
 
 @item @emph{Return value}:
 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 
-has dimensions. The elements of the resulting array correspond to the extent
+has dimensions. The elements of the resulting array correspond to the extend
 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
 the result is the rank one array of size zero.
 
@@ -8789,12 +8854,12 @@
 @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 distance between the argument @var{X} and the nearest 
+adjacent number of the same type.
+
 @item @emph{Standard}:
 F95 and later
 
@@ -8802,10 +8867,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(1.0_SGL)      ! "1.1920929E-07"          on i686
+  WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
+END PROGRAM
+@end smallexample
+
 @item @emph{See also}:
+@ref{RRSPACING}
 @end table
 
 
@@ -8815,10 +8899,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
 
@@ -8826,10 +8911,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
 
 
@@ -9019,12 +9126,13 @@
 @node SUM
 @section @code{SUM} --- Sum of array elements
 @cindex @code{SUM} intrinsic
-@cindex array manipulation
+@cindex array operation
 
-Intrinsic implemented, documentation pending.
-
 @table @asis
 @item @emph{Description}:
+Adds 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
 
@@ -9032,9 +9140,37 @@
 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 (Optional) 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 (Optional) 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{ARRAY}
+is returned. Otherwise, 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.
+
 @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
@@ -9129,10 +9265,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
 
@@ -9140,10 +9283,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} with @code{INTENT(OUT)}.
+@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default 
+@code{INTEGER} with @code{INTENT(OUT)}.
+@item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type default 
+@code{INTEGER} with @code{INTENT(OUT)}.
+@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
 
 
@@ -9360,12 +9523,15 @@
 @node TRANSFER
 @section @code{TRANSFER} --- Transfer bit patterns
 @cindex @code{TRANSFER} intrinsic
-@cindex bit operations
+@cindex type cast
 
-Intrinsic implemented, documentation pending.
-
 @table @asis
 @item @emph{Description}:
+Interprets the bit pattern of @var{SOURCE} as a variable of the 
+same type and type parameters as @var{MOLD}.
+
+This is also known as @emph{casting} one type to another.
+
 @item @emph{Standard}:
 F95 and later
 
@@ -9373,10 +9539,27 @@
 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 (Optional) 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 +9795,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 +9806,35 @@
 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 corresponds to @var{FIELD} with @code{TRUE} elements
+of @var{MASK} replaced by values from @var{VECTOR} in array element order.
+
 @item @emph{Example}:
+@smallexample
+PROGRAM test_unpack
+  integer :: vector(2)  = (/1,1/)
+  logical :: mask(2,2)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
+  integer :: field(2,2) = 0, unity(2,2)
 
+  ! result: unity matrix
+  unity = unpack(vector, reshape(mask, (/2,2/), field)
+END PROGRAM
+@end smallexample
+
 @item @emph{See also}:
-@ref{PACK}
+@ref{PACK}, @ref{SPREAD}
 @end table
 
 

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]