[Cfp-interest] functions - subgroup meeting 20100408 notes

[Jim Thomas]

*** Notes from Functions subgroup meeting 08 Apr 2010 ***

Present were Mathew, Ian, Raymond, David, and Jim.

We started through discussion notes which Jim emailed to meeting 
attendees. The notes followed the outline of new functions posted under 
Functions on the CFP wiki. We made a first pass through these function 
groups:

roundToIntegralTiesToEven
nextUp, nextDown
formatOf (narrowing) functions
minNumMag, maxNumMag
convertToInteger functions

Below is a working outline that reflects the discussion at today's meeting.

-Jim

New functions for IEEE 754-2008 support in C
Working outline


1. roundToIntegralTiesToEven

This completes C's ceil, floor, trunc, round.

ISSUE: Name? Some possibilities - roundieee, roundeven, roundte, roundunbiased, rintnr

ISSUE: C99 allows ceil etc. to signal inexact (when the result isn't equal to the 
argument) or not. Do we need another function for each of these that is guaranteed 
to not signal inexact? Could we deprecate the license to signal inexact? Could we 
disallow signaling inexact? The latter two might raise compatibility objections.


2. nextUp, nextDown

Add nextup and nextdown to C.


3. minNumMag, maxNumMag

For minNum and maxNum C has fmin and fmax.

ISSUE: Names? Possibilities include
  fminmag and fmaxmag
  fminm and fmaxm
  famin and famax

(A general issue is that C99 doesn't cover signaling NaNs.) 


4. formatOf (narrowing) addition, subtraction, multiplication, division, square root, 
and fusedMultiplyAdd

Names could follow the scheme of prefix for the result type,
a root name, and a suffix for the argument types, like lroundf, etc. Examples are

float fadd(double, double);
float faddl(long double, long double);
double addl(long double, long double);
_FloatN fNfuncfM(_FloatM, _FloatM);  // for M > N and 
                                     //   func = add, sub, mul, div, sqrt, fma
_Float32 f32funcf32x(_Float32x, _Float32x);

Widening functions aren't necessary because calling the wider function has the same
effect. 


5. convertToInteger functions, with and without inexact signal, for five
rounding modes

Signed integer types are signed char, short, int, long, long long, intN_t and
each has a corresponding unsigned integer type.

Names could follow the general scheme described in 4. The root names are
ceil, floor, trunc, round, and whatever we decide for 1. The prefixes are
sc s  i  l  ll  iN for signed
uc us ui ul ull uN for unsigned
The suffixes are the usual ones for floating types. Examples are

unsigned int uiceilf(float);
int32_t i32ceilf64(_Float64);

ISSUE: Do we need another set of function that convert to char (which may be
signed or unsigned)?

ISSUE: As in the second issue in 1, C99 allows its lround and llround to signal
inexact or not. Do add another set of round functions, deprecate signaling, or
change the spec.


6. decimal reencoding functions
     encodeDecimal, decodeDecimal (for Densely Packed Decimal encoding)
     encodeBinary, decodeBinary (for Binary Integer Decimal encoding)

Suggestion:
Add types: decimalencodingdN_t, binaryencodingdN_t
Add functions:
  decimalencodingdN_t encodedecimaldN(_DecimalN);
  _DecimalN decodedecimaldN(decimalencodingN_t);
  binaryencodingdN_t encodebinarydN(_DecimalN);
  _DecimalN decodebinarydN(binaryencodingN_t);


7. compareSignalingEqual, compareSignalingNotEqual
Maybe macros isnumeq, isnumneq


8. new inquiries

8.1   ten-way class

Declare 754 to be satisfied by fpclassify and signbit 
or define a new classification function and new macros

8.2   isSubnormal
Could be macro issubnormal()

8.3   isSignaling
Could be macro issignaling() or issnan()

8.4   isCanonical
Could be macro iscanonical()


9. totalOrder, totalOrderMag

int totalorder(double,double);
int totalorderfN(_FloatN, _FloatN);

int totalordermag(double,double);
int totalordermagfN(_FloatN, _FloatN);


10. new exception flag operations

10.1  raiseFlags (in 754-2008 "raise" means set bit)
Could be
int fesetexcept(int excepts); // like reraiseexcept but no signal

10.2  testSavedFlags
Could be
int fetestexceptflags(const fexcept_t * flagp, int excepts); // see fetestexcept and 
                                                             //   fesetexceptflag

11. Math functions

11.1 correct rounding (recommended)

Could prefix function names with cr, per prior art.
Could reserve names without requiring implementation.

11.2 new math functions (recommended)
      exp2m1
      exp10
      exp10m1
      log2p1
      log10p1
      rSqrt
      compound
      rootn
      pown
      powr
      sinPi
      cosPi
      atanPi
      atan2Pi

Could use same names but all lower case.
Need to check consistency of 754 with C99


12. defaultModes function

Could be
int fesetdflmodes();


13. Reduction functions (recommended)
  sum
  dot
  sumSquare
  sumAbs
  scaledProd
  scaledProdSum
  scaledProdDiff

Names sum and dot too short/common. Maybe sumreduc(), dotprod(), other?
Maybe match sumAbs to sum: sumabsreduc().
Other names, sans camel-case, seem ok. 

The type of the length parameter could match the array element type:
  _FloatN sumreduc(const _FloatN *, _FloatN);

Or could be an implementation defined type with at least the precision of the array
element type and maybe also at least 32 bits of precision:
  _FloatN sumreduc(const _FloatN *, reduc_lenN_t);


14. All above

Also for decimal floating types.
Also for extended types.