Document: WG14 N1355

Preferred quantum exponent for DFP math functions


Submitter: Fred Tydeman (USA)
Submission Date: 2009-02-06
Related WG14 documents: N1312
Subject: Preferred quantum exponent for DFP math functions

IEEE-754-2008 has: 9.1 Conforming language- and implementation-defined functions:

Paragraph 1: As noted below, the specificaitons for inexact exceptions and preferred quantum in previous clauses do not apply to the functions specified in this clause.

Paragraph 3: A conforming function shall return results correctly rounded for the applicable rounding direction for all operands in its domain. The preferred quantum is language-defined.

9.2.1 Special Values has several pages of specific cases (mostly for transcendental functions); they list the values, but not the preferred qunatum exponent. For example, acos(1) is +0 and acosh(1) is +0.

WG14 N1312 (TR 24732) has: 8.2 Functions

Paragraph 1: The headers and library supply a number of functions and macros that implement support for decimal floating point data with the semantics specified in IEEE 754-2008, including producing results with the preferred exponent where appropriate.

That is followed by a list of algebraic functions; which is a subset of <math.h>. The ones that matter to this document are: sqrt, frexp, ldexp, scalb*, fabs, ceil, floor, round, trunc, rint.

So, neither defines the preferred quantum exponent for transcendental DFP math functions with special values.

Various implementors that I have talked with have done different things.

Jim Thomas (HP) implemented a preferred exponent of 0 for exact cases for transcendental functions. It's a simple rule to understand and implement. It avoids surprising output (like 0e-6144). It matches the conversion to decimal of the same binary value.

Our (Intel) prototype library currently uses the minimal exponent. Originally I used zero (effective, unbiased exponent), and I still slightly prefer that choice, since it is an exact result. But our testers preferred the minimal exponent, and since I didn't feel strongly either way I was happy to accommodate them. If there are several other voices in favour of zero I'll be very happy to change back again.

I (Tydeman) would expect one argument functions where f(zero) returns zero to have as its first line of code: 

  if( isnan(x) || (0.DF==x) ) return x;
That is, the argument that comes in is the value returned. That would leave the preferred exponent alone.

IEEE-754-2008 has (on a related topic): 

   For exact conversions from binary to decimal formats,
   the preferred exponent is 0.
Earlier drafts had the preferred exponent be the maximum, i.e. trailing zeros of exact results were to be shifted out -- and an exact result of zero would have the maximum possible exponent. Such a zero has the interesting property that it is neutral for addition.

So we have four choices mentioned: 

  zero exponent
  minimal exponent
  same exponent
  maximum exponent

This list of special cases are:

Functions covered by IEEE-754-2008 and the DFP TR: 

f(x) returns x
  zero
    frexp
    ldexp(0.,any)
    scalbn(0.,any), scalbln(0.,any)
    modf ???
    sqrt
    fabs
    ceil
    floor
    nearbyint
    rint
    round
    trunc
    fmod(0.,non-zero) ???
  non-zero
    frexp(.1 <= x < 1.)
    scalbn(non-zero,0), scalbln(non-zero,0L)
f(x) returns w
  w=zero
    fdim(x,y) when x <= y ????

Functions NOT covered by IEEE-754-2008 and the DFP TR: 

f(x) returns x
  zero
    asin, sin
    atan, tan
    asinh, sinh
    atanh, tanh
    expm1
    log1p
    modf
    cbrt
    hypot(0.,0.)
    erf
    fmod(0.,non-zero)
  non-zero
    hypot(non-zero,0.)
    pow(1.,any)
f(x) returns w
  w=zero
    acos(1.)
    acosh(1.)
    log(1.)
    log10(1.)
    log2(1.)
    erfc(+inf)
    lgamma(1.), lgamma(2.)
  w=non-zero
    cos(0.) is 1.
    cosh(0.) is 1.
    exp(0.) is 1.
    exp2(0.) is 1.
    log10(10**N) is N
    log2(2**N) is N
    pow(any,0.) is 1.  [and others]
    erf(+/-inf) is +/-1.
    erfc(-inf) is 2.
    tgamma(+N) is (N-1)!