[PATCH] PR fortran/62245 fix INT docs.

[PATCH] PR fortran/62245 fix INT docs.

[VandeVondele Joost]

A doc change to refine wording for result value of int, avoiding the word range and using magnitude as does the standard. Mentions undefined behavior.

2014-08-24  Joost VandeVondele  <vondele@gcc.gnu.org>

	PR fortran/62245
	* intrinsic.texi (INT): clarify result and undefined behavior.


Index: intrinsic.texi
===================================================================
--- intrinsic.texi	(revision 214408)
+++ intrinsic.texi	(working copy)
@@ -7371,8 +7371,10 @@ the following rules:
 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 
 @item (B)
 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}. 
-If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed 
-the range of @var{A} and whose sign is the same as the sign of @var{A}.
+If @math{|A| \geq 1}, then @code{INT(A)} is the integer whose magnitude is the largest
+integer that does not exceed the magnitude of @var{A} and whose sign is the same as
+the sign of @var{A}. The result is undefined if it can not be represented as an
+@code{INTEGER} of the given @code{KIND}.
 @item (C)
 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
 @end table

Re: [PATCH] PR fortran/62245 fix INT docs.

[Gerald Pfeifer]

On Sun, 24 Aug 2014, VandeVondele  Joost wrote:
> A doc change to refine wording for result value of int, avoiding the 
> word range and using magnitude as does the standard. Mentions undefined 
> behavior.
> 
> 2014-08-24  Joost VandeVondele  <vondele@gcc.gnu.org>
> 
> 	PR fortran/62245
> 	* intrinsic.texi (INT): clarify result and undefined behavior.

Looks good to me, though better wait for a Fortran maintainer to be
sure.

One small ask:  these lines are too long (already before your patch);
can you please reformat those lines your patch touches to <80 columns?

Thanks,
gerald

RE: [PATCH] PR fortran/62245 fix INT docs.

[VandeVondele Joost]

> One small ask:  these lines are too long (already before your patch);
> can you please reformat those lines your patch touches to <80 columns?

sure:

Index: intrinsic.texi
===================================================================
--- intrinsic.texi	(revision 214408)
+++ intrinsic.texi	(working copy)
@@ -7370,9 +7370,12 @@ the following rules:
 @item (A)
 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 
 @item (B)
-If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}. 
-If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed 
-the range of @var{A} and whose sign is the same as the sign of @var{A}.
+If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
+equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
+whose magnitude is the largest integer that does not exceed the magnitude
+of @var{A} and whose sign is the same as the sign of @var{A}. The result
+is undefined if it can not be represented as an @code{INTEGER} of the
+given @code{KIND}.
 @item (C)
 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
 @end table

Re: [PATCH] PR fortran/62245 fix INT docs.

[Steve Kargl]

On Sun, Aug 24, 2014 at 12:47:18PM +0000, VandeVondele  Joost wrote:
> > One small ask:  these lines are too long (already before your patch);
> > can you please reformat those lines your patch touches to <80 columns?
> 
> sure:
> 
> +of @var{A} and whose sign is the same as the sign of @var{A}. The result
> +is undefined if it can not be represented as an @code{INTEGER} of the
> +given @code{KIND}.

The last sentence above is not needed.  There is a general
prohibition in 13.7.1 against calling INT(A) with |A| > HUGE(1_4).

-- 
Steve

RE: [PATCH] PR fortran/62245 fix INT docs.

[VandeVondele Joost]

>> +of @var{A} and whose sign is the same as the sign of @var{A}. The result
>> +is undefined if it can not be represented as an @code{INTEGER} of the
>> +given @code{KIND}.
>
>The last sentence above is not needed.  

but helpful for gfortran users ?

> There is a general
> prohibition in 13.7.1 against calling INT(A) with |A| > HUGE(1_4).

maybe you could prepare a patch to add something like that to the section on intrinsics ?

Re: [PATCH] PR fortran/62245 fix INT docs.

[Steve Kargl]

On Sun, Aug 24, 2014 at 03:58:42PM +0000, VandeVondele  Joost wrote:
> >> +of @var{A} and whose sign is the same as the sign of @var{A}. The result
> >> +is undefined if it can not be represented as an @code{INTEGER} of the
> >> +given @code{KIND}.
> >
> >The last sentence above is not needed.  
> 
> but helpful for gfortran users ?
> 

The problem is that a similar sentence would then need to be
added to other intrinsic subroutines/functions where an actual
argument might produce a result that is out-of-range of the
representable entity.  Note, that it isn't limited to just
the conversion functions.  Consider IABS() and the asymetric
range of the INTEGERi type.

integer i
i = - huge(i) - 1
print *, iabs(i)
end

> > There is a general
> > prohibition in 13.7.1 against calling INT(A) with |A| > HUGE(1_4).
> 
> maybe you could prepare a patch to add something like that to the
> section on intrinsics?

Sure, I'll come up with a statement to be added to Sec. 8.1 of
the gfortran manual.

-- 
Steve

RE: [PATCH] PR fortran/62245 fix INT docs.

[VandeVondele Joost]

>> but helpful for gfortran users ?
>The problem is that a similar sentence would then need to be
>added to other intrinsic subroutines/functions where an actual
>argument might produce a result that is out-of-range of the
>representable entity.  

So, I could remove the sentence if there is consensus.

>> maybe you could prepare a patch to add something like that to the
>> section on intrinsics?
>
>Sure, I'll come up with a statement to be added to Sec. 8.1 of
>the gfortran manual.

actually, it is more complicated, since gfortran does support things such as NaN, and Inf, depending on the hardware and the compilation options.

RE: [PATCH] PR fortran/62245 fix INT docs.

[VandeVondele Joost]

> >The last sentence above is not needed.

So, revised patch without the last sentence.

2014-09-05  Joost VandeVondele  <vondele@gcc.gnu.org>

	PR fortran/62245
	* intrinsic.texi (INT): clarify result.

Index: fortran/intrinsic.texi
===================================================================
--- fortran/intrinsic.texi	(revision 214949)
+++ fortran/intrinsic.texi	(working copy)
@@ -7370,9 +7370,10 @@ the following rules:
 @item (A)
 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 
 @item (B)
-If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}. 
-If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed 
-the range of @var{A} and whose sign is the same as the sign of @var{A}.
+If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
+equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
+whose magnitude is the largest integer that does not exceed the magnitude
+of @var{A} and whose sign is the same as the sign of @var{A}.
 @item (C)
 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
 @end table

Re: [PATCH] PR fortran/62245 fix INT docs.

[Steve Kargl]

On Fri, Sep 05, 2014 at 11:16:02AM +0000, VandeVondele  Joost wrote:
> > >The last sentence above is not needed.
> 
> So, revised patch without the last sentence.
> 
> 2014-09-05  Joost VandeVondele  <vondele@gcc.gnu.org>
> 
> 	PR fortran/62245
> 	* intrinsic.texi (INT): clarify result.
> 

OK.

-- 
Steve

RE: [PATCH] PR fortran/62245 fix INT docs.

[VandeVondele Joost]

> OK.

Committed revision 214958.