From patchwork Tue Jun 7 07:09:24 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rical Jasan X-Patchwork-Id: 12829 Received: (qmail 70179 invoked by alias); 7 Jun 2016 07:09:41 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 70086 invoked by uid 89); 7 Jun 2016 07:09:41 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.6 required=5.0 tests=AWL, BAYES_50, RCVD_IN_DNSWL_NONE, RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=SUCCESS, lastly, Mathematics, mathematics X-HELO: mail.pacific.net Subject: Re: [PATCH v3] Add nextup and nextdown math functions To: Rajalakshmi Srinivasaraghavan References: <201606011211.u51C9sVN019582@mx0a-001b2d01.pphosted.com> <574FE5C6.6040303@pacific.net> <201606061715.u56HEkNN001197@mx0a-001b2d01.pphosted.com> Cc: libc-alpha@sourceware.org, Joseph Myers , "Paul E. Murphy" From: Rical Jasan Message-ID: <57567324.6030301@pacific.net> Date: Tue, 7 Jun 2016 00:09:24 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.8.0 MIME-Version: 1.0 In-Reply-To: <201606061715.u56HEkNN001197@mx0a-001b2d01.pphosted.com> X-Null-Tag: 26f33bd76fc2d5eec73ab98392e5e604 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