[fortran, documentation, patch] document the last set of intrinsics
Daniel Franke
franke.daniel@gmail.com
Thu Apr 26 23:49:00 GMT 2007
> > 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: intrinsic.texi.diff
Type: text/x-diff
Size: 12839 bytes
Desc: not available
URL: <http://gcc.gnu.org/pipermail/gcc-patches/attachments/20070426/f3a7abcb/attachment.bin>
More information about the Gcc-patches
mailing list