This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] Add nextup and nextdown math functions
- From: Rical Jasan <ricaljasan at pacific dot net>
- To: Rajalakshmi Srinivasaraghavan <raji at linux dot vnet dot ibm dot com>
- Cc: libc-alpha at sourceware dot org, Joseph Myers <joseph at codesourcery dot com>
- Date: Thu, 2 Jun 2016 00:52:38 -0700
- Subject: Re: [PATCH] Add nextup and nextdown math functions
- Authentication-results: sourceware.org; auth=none
- References: <201606011211 dot u51C9sVN019582 at mx0a-001b2d01 dot pphosted dot com>
> diff --git a/manual/arith.texi b/manual/arith.texi
> index 72682f0..a869922 100644
> --- a/manual/arith.texi
> +++ b/manual/arith.texi
> @@ -1687,6 +1687,25 @@ This function is defined in @w{IEC 559} (and the appendix with
> recommended functions in @w{IEEE 754}/@w{IEEE 854}).
> @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 value
> +less than @var{x}. If @var{x} is the positive number of least
> +magnitude the function returns +0. If @var{x} is zero, the function returns
> +the negative number of least magnitude in the type of @var{x}.
Is +0 not considered a positive number?
The manual is all over the place with this, but there is a strong
tendency to wrap numbers, esp. where they're return values and such, in
@code{}, so "returns @code{+0}." @math{} is also used for formatting
numbers, but not nearly as widely.
Similar question for -0, and whether it is considered a negative number.
Also, does zero in "If @var{x} is zero" imply all of -0, 0, and +0?
> +nextdown(@code{-HUGE_VAL}) is @code{-HUGE_VAL}. It is based on draft
I can't recall ever seeing a function call within a paragraph, and
haven't been able to find an example, skimming through the manual. I
suggest using a similar style to what you've already used (i.e., "If
@var{x} is @code{-HUGE_VAL}, the return value is @code{-HUGE_VAL}.") or
breaking it out into a @smallexample and rearranging/rewording as necessary.
There is a good flow here, though: I found myself asking what happens if
you have the lowest number once the zero case was mentioned, and then
you answered it right away. :)
I think changing "It" to @code{nextdown} would be nice; it feels like
it's somehow talking about HUGE_VAL, or specifically that aforementioned
outcome. Also, it will be necessary if you change the subject of the
HUGE_VAL sentence to x or move it to its own paragraph following a
@smallexample.
> +TS 18661 and currently enabled as a GNU extension.
> +@end deftypefun
> +
> @comment math.h
> @comment ISO
> @deftypefun double nexttoward (double @var{x}, long double @var{y})
> @@ -1702,6 +1721,25 @@ These functions are identical to the corresponding versions of
Is there a reason you split these new descriptions apart across
nexttoward? nextafter and nexttoward are related to each other, and
nextup and nextdown are also their own pair.
> 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 value
> +greater than @var{x}. If @var{x} is the negative number of least
> +magnitude the function returns -0. If @var{x} is zero, the function returns
> +the positive number of least magnitude in the type of @var{x}.
> +nextup(@code{HUGE_VAL}) is @code{HUGE_VAL}. It is based on draft
> +TS 18661 and currently enabled as a GNU extension.
> +@end deftypefun
> +
> @cindex NaN
> @comment math.h
> @comment ISO
Same comments/questions on nextup as nextdown.
Thanks for documenting your work on the new stuff!
Rical