IEEE(3) —

NAME

copysign, drem, logb, scalb, rint, classdouble, classfloat, isnan, unordered, finite, infinity, nextdouble, nextfloat, fptestround, fpsetround, swapround, fptestflag, fpsetflag, fpclrflag, swapfpflag, fptesttrap, fpsettrap, fpclrtrap, swapfptrap − ieee arithmetic support functions

SYNOPSIS

#include <ieee.h>

double copysign(x, y)
double x, y;

double drem(x, y)
double x, y;

double logb(x)
double x;

double scalb(x, n)
double x;
int n;

double rint(x)
double x;

NUMCLASS classdouble(x)
double x;

NUMCLASS classfloat(x)
double x;

int isnan(x)
double x;

int unordered(x, y)
double x, y;

int finite(x)
double x;

double infinity();

double nextdouble(x, y)
double x, y;

float nextfloat(x, y)
double x, y;

ROUNDDIR fptestround();

void fpsetround(r)
ROUNDDIR r;

ROUNDDIR swapround(r)
ROUNDDIR r;

FPEXCEPTION fptestflag();

void fpsetflag (m)
FPEXCEPTION m;

void fpclrflag(m)
FPEXCEPTION m;

FPEXCEPTION swapfpflag(m, e)
FPEXCEPTION m, e;

FPEXCEPTION fptesttrap();

void fpsettrap(m)
FPEXCEPTION m;

void fpclrtrap(m)
FPEXCEPTION m;

FPEXCEPTION swapfptrap(m, e)
FPEXCEPTION m, e;

DESCRIPTION

These functions are necessary for, or recommended by, the IEEE standard 754 for binary floating-point arithmetic. They observe the rounding mode and set exception flags as appropriate.

Copysign returns x with the sign of y.

Drem returns r when y is not equal to 0; the remainder r is defined by the mathematical relation

r = x - y∗n

where n is the integer nearest the exact value x/y; whenever |n-x/y|=1/2, then n is even. Consequently the remainder is computed exactly and |r| ≤ |y|/2. But drem(x,0) and drem(∞,y) are exceptional; see below under “Diagnostics”.

Logb returns the exponent of x, a signed integer represented as a double precision number. Here the exponent of x is defined to be the integer n such that 1<=|x/(2n)|<2 unless x = 0 or |x| = ∞ ; see “Bugs”. If the magnitude of x is ∞, logb returns ∞. Log(0) is exceptional; see below under “Diagnostics."

Scalb returns x∗(2n), for integer values n without computing 2n.

Rint returns x rounded to an integral value, according to the current rounding mode. In the default rounding mode, round-to-nearest, rint(x) is the integer nearest x with the additional stipulation that |rint(x) - x| = 1/2, then rint(x) is even. Other rounding modes can make rint act like floor, or like ceil, or round toward zero.

Classdouble and classfloat return the numerical class of x, which is either signaling NaN (SNAN), quiet NaN (QNAN), infinity (INFINITE), zero (ZERONUM), denormal (DENORMALNUM), or normal (NORMALNUM).

Isnan returns a value of 1 if x is a NaN (not-a-number); otherwise, it returns 0.

Unordered returns a value of 1 if x is unordered with y (i.e., x or y is a NaN); otherwise, it returns 0.

Finite returns a value of 1 if −∞ < x < ∞; otherwise, it returns 0.

Infinity returns the value ∞.

Nextdouble and nextfloat return the next representable neighbor of x in the direction toward y.

Fptestround returns the current rounding mode.

Fpsetround sets the rounding mode to r .

Swapround sets the rounding mode to r and returns the previous rounding mode.

Fptestflag returns the current status of all exception flags.

Fpsetflag sets the exception flags marked in mask m .

Fpclrflag clears the exception flags marked in mask m .

Swapfpflag sets each exception flag marked in mask m to the corresponding setting (1=set, 0=clear) in e, and returns the previous status of each flag. If the mask is 0, no flag is changed and the current status of each flag marked in e is returned.

Fptesttrap returns the current setting of all exception traps.

Fpsettrap enables traps for the exceptions marked in mask m .

Fpclrtrap disables traps for the exceptions marked in mask m .

Swapfptrap sets each exception trap marked in the mask m to the corresponding setting (1=enables, 0=disables) in e, and returns the previous setting of each exception trap. If the mask is 0, no exception trap is changed and the current setting of each exception trap marked in e is returned.

<ieee.h> has the following form:

/∗
∗ 5799-WZQ (C) COPYRIGHT IBM CORPORATION 1986,1987
∗ LICENSED MATERIALS - PROPERTY OF IBM
∗ REFER TO COPYRIGHT INSTRUCTIONS FORM NUMBER G120-2083
∗/
/∗ ieee.h
∗/
/∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗/
/∗   types for recommended functions and support routines   ∗/
/∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗/
typedef enum { /∗ allows user setting and   ∗/
TONEAREST, /∗ clearing of rounding mode   ∗/
UPWARD,
DOWNWARD,
TOWARDZERO
} ROUNDDIR;
typedef enum {/∗ every ieee floating point   ∗/
SNAN,/∗ value is in one and only one   ∗/
QNAN,/∗ of these classes   ∗/
INFINITE,
ZERONUM,
NORMALNUM,
DENORMALNUM
} NUMCLASS;
#define FPINVALID1/∗ allows user to set and clear    ∗/
#define FPUNDERFLOW2/∗ floating point exception flags ∗/
#define FPOVERFLOW4/∗ and traps   ∗/
#define FPDIVBYZERO8
#define FPINEXACT16
#define FPALLEXCEPTIONS 0x1f
typedef short FPEXCEPTION;/∗ a sum of particular exceptions ∗/
/∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗/
/∗   IEEE recommended functions and recommended support routines.   ∗/
/∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗/
double copysign(), rint(), scalb(), logb(), drem(), nextdouble(), infinity();
float nextfloat();
NUMCLASS classfloat(), classdouble();
FPEXCEPTION swapfpflag(), fptestflag();
void fpsetflag(), fpclrflag();
FPEXCEPTION swapfptrap(), fptesttrap();
void fpsettrap(), fpclrtrap();
ROUNDDIR swapround(), fptestround();
void fpsetround();
/∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗/
/∗   Mode specifiers for conversion (ecvt, fcvt) rounding.   ∗/
/∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗/
#defineCVT_ROUND0/∗ rounding "to-roundest"   ∗/
#defineCVT_IEEE1/∗ uses ieee rounding   ∗/

DIAGNOSTICS

Drem returns a NaN when y is equal to 0 or x is infinite; in both cases an invalid operation exception is raised.

Logb returns −∞ when x is equal to 0, and signals the division by zero exception.

NOTES

The IEEE 754 Standard for Binary Floating Point Arithmetic can be obtained from:

IEEE Standards Office
345 East 47th Street
New York, NY 10017

BUGS

Classfloat will never return SNAN. (All float arguments get converted to double before being passed to a routine; thus, a signaling NaN, upon conversion, will become quiet before classfloat receives it.)

IEEE 754 currently specifies that logb(denormalized no.) = logb(tiniest normalized no. > 0) but the consensus has changed to the specification in the new IEEE standard 854, namely that logb(x) satisfy

1 ≤ scalb(|x|,−logb(x)) < Radix (Radix = 2 for IEEE 754)

for every x except 0, ∞ and NaN. Almost every program that assumes 754’s specification will work correctly if logb follows 854’s specification instead. In IBM/4.3, logb() is implemented using 854’s specification.

Museum

Related Articles