[Cfp-interest] functions - subgroup meeting 20100513 notes

[Jim Thomas]

*** Notes from Functions subgroup meeting 13 May 2010 ***

Present were Mathew Koshy, Fred Tydeman, Steve Canon, David Hough, Ian 
McIntosh, Raymond Mak, Robert Enenkel, and Jim Thomas.

We picked up were we left off at the previous Functions subgroup 
meeting, at item 6 in the working outline posted on the CFP wiki under 
Topics/Functions/Attachments. We completed a first pass through the 
outline. The outline below (and posted on the wiki) has been updated 
based on the meeting discussion. Note several significant changes, in 
items 6, 7, 8.1, 8.4, 10.1, 12, and 13. We also spent a few minutes 
discussing item 5, leading to the new second issue there.

-Jim

---------------------------------------------------
	
New functions for IEEE 754-2008 support in C
Working outline
Updated 13 May 2010


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);

Functions that signal inexact might be distinguished by an x just before 
or after the root name, e.g., uixceilf or uiceilxf.

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

ISSUE: The above scheme requires 5*12*2 = 120 functions for each 
floating-point type, even without functions for a separate char type or 
the intN_t and uintN_t types. This is a lot of functions.

ISSUE: As in the second issue in 1, C99 allows its lround and llround to 
signal inexact or not. Do we 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)
These were rejected for the decimal FP TR, but are truly needed because 
conversion between the encodings is tedious (much more so than for 
endianness).
Suggestion:
Add types: dpdencodingdN_t, bidencodingdN_t
Add functions:
	dpdencodingdN_t encodedpddN(_DecimalN);
	_DecimalN decodedpddN(dpdencodingN_t);
	bidencodingdN_t encodebiddN(_DecimalN);
	_DecimalN decodebiddN(bidencodingN_t);


7. compareSignalingEqual, compareSignalingNotEqual
Could be macros iseqsig(), isnesig()


8. new inquiries

8.1   ten-way class
We can declare 754 to be satisfied by the existing fpclassify and 
signbit function macros. Requiring a new function macro like fpclassify 
but doing a 10-way classification doesn't seem necessary.

ISSUE: Do we also want an inquiry that takes a mask argument that can 
specify combinations of the ten classes? Robert, Ian, and Raymond will 
propose a spec.

8.2   isSubnormal
Could be macro issubnormal()

8.3   isSignaling
Could be macro issignaling()

8.4   isCanonical
Could be macro iscanonical()

ISSUE: Need to specify what canonical means, for binary as well as 
decimal types.

9. totalOrder, totalOrderMag
Could be, for example:
	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

ISSUE: Is this implementable for the x87 pending exception mechanism? 
Implementations with SSE can avoid this problem by just setting flags in 
the MXCSR register and not in the x87 status register.

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 
these cr-prefixed 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.

ISSUE: Need to check consistency of 754 with C99.


12. defaultModes function
Could be just
	int fesetdflmodes();

But not very useful unless there's a way to save and restore the modes. 
Following the fenv.h style, we could have an opaque type representing 
the implementation's floating-point modes (rounding direction and any 
extension modes, including trap enablement, sudden underflow, and 
rounding precision modes)

	femode_t

a macro whose type is pointer to const-qualified femode_t.

	FE_DFL_MODE

and two functions

	int fegetmode(femode_t *modep);
	int fesetmode(femode_t *modep);
	
Then typical use is

	#include <fenv.h>
	femode_t savemodes;
	fegetmode(&savemodes);
	fesetmode(FE_DFL_MODE);
	...
	fesetmode(&savemodes);

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

Names could be the same, except all lower case and with a prefix: 
reduc_sum, ... reduc_scaledproddiff. This would have the advantage of 
grouping them in documentation indexes.

The length type could be size_t.

ISSUE: Need actual interfaces and specifications. David will draft these.


14. All above

Also for decimal floating types.
Also for extended types.