Re: [PATCH v3] Add nextup and nextdown math functions

[Rical Jasan <ricaljasan at pacific dot net>]

On 06/06/2016 10:15 AM, Rajalakshmi Srinivasaraghavan wrote:
> diff --git a/NEWS b/NEWS
> index 2341697..7aa6133 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -33,6 +33,13 @@ Version 2.24
>    group: files [SUCCESS=merge] nis
>    Implemented by Stephen Gallagher (Red Hat).
>  
> +* nextupl, nextup, nextupf, nextdownl, nextdown and nextdownf are added
> +  to libm. They are defined by TS 18661 and IEEE754-2008. The nextup functions
> +  return the next representable value in the direction of positive infinity
> +  and the nextdown functions return the next representable value in the
> +  direction of negative infinity.  These are currently enabled as GNU
> +  extension.

extensions

> +
>  Security related changes:
>  
>  * An unnecessary stack copy in _nss_dns_getnetbyname_r was removed.  It
> diff --git a/manual/arith.texi b/manual/arith.texi
> index 72682f0..ec46699 100644
> --- a/manual/arith.texi
> +++ b/manual/arith.texi
> @@ -1702,6 +1702,40 @@ These functions are identical to the corresponding versions of
>  double}.
>  @end deftypefun
>  
> +@comment math.h
> +@comment GNU
> +@deftypefun double nextup (double @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx float nextupf (float @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx {long double} nextupl (long double @var{x})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +The @code{nextup} function returns the next representable neighbor of
> +@var{x} in the direction of positive infinity.  If @math{@var{x} =  @code{0}}

one space after =

> +the function returns the positive number of least magnitude in the type of
> +@var{x}.  If @var{x} is @code{NaN}, @code{NaN} is returned.  @code{nextup}

To adhere to the majority style of the Arithmetic chapter, those NaNs
would not be enclosed in @code{} (57:2).  In fact, their appearance in
@code{} in nextafter is the only place in the chapter that happens (and
only one other time in Mathematics).  Personally, I thought it was
strange they were all unformatted, and they probably should be
@code{NaN}, but I wanted to mention it for the sake of consistent style.

I feel like we lost information here.  Before, you had an example with
HUGE_VAL, which is gone now, but NaN showed up.  I'm not a
floating-point expert, and because of that I would like more detail
regarding the behaviour of the functions (might also be why I have so
many questions :).

The function descriptions in this chapter are pretty minimalistic, which
I think has something to do with the amount of auxiliary information
presented throughout -- this chapter does a very good job of introducing
its subject matter and providing general information on it -- but I
think we can give a description that would make our documentation of
nextup/down superior to the rest.

I've attached the beginnings of how I would approach it, but there are
some questions embedded as comments in there, which I also mention
below.  The general strategy is to attempt to address the functions'
behaviour when given any of the classifications of floating-point
numbers, as outlined in fpclassify, 20.4 Floating-Point Number
Classification Functions (NaN, infinity, 0, subnormal, normal).
Hopefully my understanding of the target values is correct, and I am
referencing the Floating Point Parameters in Appendix A correctly.

I noticed issignaling (20.4) mentions a signalling NaN (sNaN), and its
description also mentions it is part of TS 18661 and is a GNU extension.
 Is that relevant or treated specially in any way?

It seems like the really interesting case is what nextup and nextdown do
when they should increment away from their respective infinities.  I can
reason returning both infinity or the next largest value, and I can't
find anything in your documentation about those cases, so I definitely
think those need clarification.

Are subnormals treated differently than normals?  It sounds like
subnormals have their own special representation, and I'm not sure if
the step sizes between them are different than for normals.  If they
are, then do nextup and nextdown use the step size for subnormals when
given a subnormal or do they convert to the next higher or lower
normalized value (which I guess would essentially be, for example,
+/-FLT_MIN)?  Perhaps this is what "representable" is meant to imply,
but as I mentioned, not my area of expertise.  Maybe a short plug to the
effect of, "If @var{x} is subnormal, the positive/negative number of
least magnitude or zero is returned."?

Lastly, is there anything to say about floating-point exceptions?  From
a brief review of the chapter, that's the only other general topic that
caught my eye.  It's probably fine to not mention them if the behaviour
of nextup/down is as described in 20.5.1 FP Exceptions (actually, looks
like you depend on it in nextup, where you: if (isnan(x) return x + x;).
 My guess is that's why most descriptions don't mention them, but a good
number do (rint/nearbyint [inexact when arg not integer], fmod/drem
[domain error on division by zero], copysign [never]).

> +is based on TS 18661 and currently enabled as a GNU extension.
> +@end deftypefun
> +
> +@comment math.h
> +@comment GNU
> +@deftypefun double nextdown (double @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx float nextdownf (float @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx {long double} nextdownl (long double @var{x})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +The @code{nextdown} function returns the next representable neighbor of
> +@var{x} in the direction of negative infinity.  If @math{@var{x} =  @code{0}}
> +the function returns the negative number of least magnitude in the type of
> +@var{x}.  If @var{x} is @code{NaN}, @code{NaN} is returned.  @code{nextdown}
> +is based on TS 18661 and currently enabled as a GNU extension.
> +@end deftypefun
> +
>  @cindex NaN
>  @comment math.h
>  @comment ISO

Rical

diff --git a/manual/arith.texi b/manual/arith.texi
index 7daf904..5032cc9 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -1702,6 +1702,66 @@ These functions are identical to the corresponding versions of
 double}.
 @end deftypefun
 
+@comment math.h
+@comment GNU
+@deftypefun double nextup (double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx float nextupf (float @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx {long double} nextupl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{nextup} function returns the next representable neighbor of
+@var{x} in the direction of positive infinity.  The size of the step
+between @var{x} and the result depends on the type.  If
+@math{@var{x} = @code{0}}, the function returns the positive number of
+least magnitude in the type of @var{x} (e.g., @code{FLT_MIN};
+@pxref{Floating Point Parameters}).
+@c What about sNaN?
+If @var{x} is NaN, NaN is returned.
+If @var{x} is @code{INFINITY}, @code{INFINITY} is returned.
+@c Or, seeing as how there is an infinite step between
+@c -INFINITY and -FLT_MAX, is -INFINITY returned?
+If @var{x} is @code{-INFINITY}, the largest representable negative number
+is returned (e.g., @code{-FLT_MAX}; @pxref{Floating Point
+Parameters}).
+@c Any mention of subnormal vs. normal?
+@c Anything to say about exceptions, interesting or otherwise?
+
+This function is based on TS 18661 and is a GNU extension.
+@end deftypefun
+
+@comment math.h
+@comment GNU
+@deftypefun double nextdown (double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx float nextdownf (float @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx {long double} nextdownl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{nextdown} function returns the next representable neighbor of
+@var{x} in the direction of negative infinity.  The size of the step
+between @var{x} and the result depends on the type.  If
+@math{@var{x} = @code{0}}, the function returns the negative number of
+least magnitude in the type of @var{x} (e.g., @code{-FLT_MIN};
+@pxref{Floating Point Parameters}).
+@c What about sNaN?
+If @var{x} is NaN, NaN is returned.
+If @var{x} is @code{-INFINITY}, @code{-INFINITY} is returned.
+@c Or, seeing as how there is an infinite step between
+@c INFINITY and FLT_MAX, is INFINITY returned?
+If @var{x} is @code{INFINITY}, the largest representable positive number
+is returned (e.g., @code{FLT_MAX}; @pxref{Floating Point
+Parameters}).
+@c Any mention of subnormal vs. normal?
+@c Anything to say about exceptions, interesting or otherwise?
+
+This function is based on TS 18661 and is a GNU extension.
+@end deftypefun
+
 @cindex NaN
 @comment math.h
 @comment ISO