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

[Rical Jasan <ricaljasan at pacific dot net>]

On 06/09/2016 09:35 AM, Rajalakshmi Srinivasaraghavan wrote:
> diff --git a/manual/arith.texi b/manual/arith.texi
> index 72682f0..18fad9f 100644
> --- a/manual/arith.texi
> +++ b/manual/arith.texi
> @@ -1702,6 +1702,44 @@ 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 @var{x} is the negative number of
> +least magnitude in the type of @var{x} the function returns @code{-0}.  If
> +@math{@var{x} = @code{0}} 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.  If @var{x} is @math{+@infinity{}}, @math{+@infinity{}} is returned.
> +@code{nextup} 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 @var{x} is the positive number of
> +least magnitude in the type of @var{x} the function returns @code{+0}.  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.  If @var{x} is @math{-@infinity{}}, @math{-@infinity{}} 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

These sound much better to me!  I think the clincher is the language:
"positive/negative number of least magnitude in the type of".  Feels
succinct, yet all-encompassing.

Hopefully this is small enough to not be annoying, and not small enough
to be annoying, but the only question I have is should we give a mention to:

On 06/07/2016 10:24 AM, Joseph Myers wrote:
> On Tue, 7 Jun 2016, Rical Jasan wrote:
>> Lastly, is there anything to say about floating-point exceptions?
> Only that these functions raise no exceptions except for sNaNs.

Though maybe that is implied somehow in the behaviour described above?
I'm unsure of when an sNaN exception is raised versus a qNaN, and the
description doesn't distinguish.  Otherwise this is great.

Thank you,
Rical