Manipulations of IEEE-754 format numbers [Float-point functions]

IEEE-754 format aware functions. More...

Defines
#define	fpclassify(x)   (sizeof(x)==sizeof(float)?_blm_fpclassf(x):_blm_fpclassd(x))
	Classifies a real expression.
#define	isnan(x)   (sizeof(x)==sizeof(float)?_blm_isnanf(x):_blm_isnand(x))
	Checks if a real expression is Not A Number.
#define	isinf(x)   (sizeof(x)==sizeof(float)?_blm_isinff(x):_blm_isinfd(x))
	Checks if a real expression is infinite.
#define	isfinite(x)   (sizeof(x)==sizeof(float)?_blm_isfinf(x):_blm_isfind(x))
	Checks if a real expression is a finite number.
#define	iszero(x)   (sizeof(x)==sizeof(float)?_blm_iszerof(x):_blm_iszerod(x))
	Checks if a real expression is zero.
#define	signbit(x)   (sizeof(x)==sizeof(float)?_blm_isnegf(x):_blm_isnegd(x))
	Checks if a real expression is negative.
#define	isnormal(x)   (fpclassify(x)==FP_NORMAL)
	Checks if a real expression is normalised.
Functions
double	ceil (double x)
	Rounds a number up to the nearest integer.
float	ceilf (float x)
	Rounds a number up to the nearest integer.
double	copysign (double a, double b)
	Changes a signum of a double to that of an other double.
float	copysignf (float a, float b)
	Changes a signum of a double to that of an other double.
double	fabs (double d)
	Absolute value of a double-precision float-point number.
float	fabsf (float f)
	Absolute value of a single-precision float-point number.
double	floor (double x)
	Rounds a number down to the nearest integer.
float	floorf (float x)
	Rounds a number down to the nearest integer.
double	frexp (double x, int *p)
	Splits a double number to a double mantissa and an integer exponent.
float	frexpf (float x, int *p)
	Splits a float number to a float mantissa and an integer exponent.
double	infinity (void)
	Returns positive infinity.
float	infinityf (void)
	Returns positive infinity.
double	ldexp (double x, int p)
	Multiplies a double with an integer power of 2.
float	ldexpf (float x, int p)
	Multiplies a float with an integer power of 2.
double	modf (double x, double *i)
	Extracts the signed integral and fractional parts of a number.
float	modff (float x, float *i)
	Extracts the signed integral and fractional parts of a number.
double	nan (const char *unused)
	Return a not-a-number.
float	nanf (const char *unused)
	Return a not-a-number.
double	round (double x)
	Round a number to the nearest integer.
float	roundf (float x)
	Round a number to the nearest integer.
double	trunc (double x)
	Truncate the number to the next integer towards zero.
float	truncf (float x)
	Truncate the number to the next integer towards zero.

---

Detailed Description

IEEE-754 format aware functions.

These functions and macros provide access to features that are IEEE-754 format specific and perform basic operations that need to know the actual internal representation of IEEE-754 numbers. They are pretty simple and fairly fast.

---

Define Documentation

#define fpclassify

(

x

)

(sizeof(x)==sizeof(float)?_blm_fpclassf(x):_blm_fpclassd(x))

Classifies a real expression.

Returns the float point class of the expression. The FP_XXX classes are anonymously defined as small integer values.

Parameters:

x

A float or double expression.

Return values:

	FP_NAN	The expression is not a number
	FP_INFINITE	The expression is infinite
	FP_ZERO	The expression is zero
	FP_SUBNORMAL	The expression is a denormalised number
	FP_NORMAL	The expression is none of the above, it is a normal real number within the full-precision representation boundaries.

#define isfinite

(

x

)

(sizeof(x)==sizeof(float)?_blm_isfinf(x):_blm_isfind(x))

Checks if a real expression is a finite number.

The macro returns 1 if the expression's value is a finite number and 0 otherwise. If the argument is not a float or double expression, then the behaviour is unspecified.

Parameters:

x

A float or double expression.

Returns:

1 if x is finite, 0 otherwise.

#define isinf

(

x

)

(sizeof(x)==sizeof(float)?_blm_isinff(x):_blm_isinfd(x))

Checks if a real expression is infinite.

The macro returns +1 if the expression's value is +infinity, -1 if the expression's value is -infinity and 0 otherwise. If the argument is not a float or double expression, then the behaviour is unspecified.

Parameters:

x

A float or double expression.

Returns:

+1, 0 or -1 depending on whether x is (signed) infinite or not.

#define isnan

(

x

)

(sizeof(x)==sizeof(float)?_blm_isnanf(x):_blm_isnand(x))

Checks if a real expression is Not A Number.

The macro returns non-zero (actually 1) if its argument is a NaN, 0 otherwise. If the argument is not a float or double expression, then the behaviour is unspecified.

Parameters:

x

A float or double expression.

Returns:

A flag indicating whether the expression is NaN

#define isnormal

(

x

)

(fpclassify(x)==FP_NORMAL)

Checks if a real expression is normalised.

The macro returns 1 if the argument is a normalised number, 0 otherwise. If the argument is not a float or double expression, then the behaviour is unspecified.

Parameters:

x

A float or double expression.

Returns:

1 if the expression is normalised, 0 otherwise.

#define iszero

(

x

)

(sizeof(x)==sizeof(float)?_blm_iszerof(x):_blm_iszerod(x))

Checks if a real expression is zero.

The macro returns +1 if the expression's value is +0, -1 if the expression's value is -0 and 0 otherwise. If the argument is not a float or double expression, then the behaviour is unspecified.

Parameters:

x

A float or double expression.

Returns:

+1, 0 or -1 depending on whether x is (signed) zero or not.

#define signbit

(

x

)

(sizeof(x)==sizeof(float)?_blm_isnegf(x):_blm_isnegd(x))

Checks if a real expression is negative.

The macro returns 1 if the signum bit of the expression is set, 0 otherwise. Note that the signum bit is undefined for NaNs. In any other case the signum bit is valid. If the argument is not a float or double expression, then the behaviour is unspecified.

Parameters:

x

A float or double expression.

Returns:

1 if the expression is negative, 0 otherwise.

---

Function Documentation

double ceil

(

double

x

)

Rounds a number up to the nearest integer.

If the argument is infinite, NaN, zero or a value that represents an integer, then the value is returned as it is. For all other values the value representing the smallest integer that is not smaller than the argument is returned. That is, for negative numbers the fractional part is simply discarded, for positive numbers the fractional part is discarded and 1 is added to the number. E.g. 2.5 will change to 3.0 but -2.5 will be changed to -2.0.

Parameters:

x

The number to calculate the ceil of

Returns:

The ceil of x, or x if x is already an integer, is infinite, is zero or is not a number.

float ceilf

(

float

x

)

Rounds a number up to the nearest integer.

If the argument is infinite, NaN, zero or a value that represents an integer, then the value is returned as it is. For all other values the value representing the smallest integer that is not smaller than the argument is returned. That is, for negative numbers the fractional part is simply discarded, for positive numbers the fractional part is discarded and 1 is added to the number. E.g. 2.5 will change to 3.0 but -2.5 will be changed to -2.0.

Parameters:

x

The number to calculate the ceil of

Returns:

The ceil of x, or x if x is already an integer, is infinite, is zero or is not a number.

double copysign	(	double	a,
		double	b
	)

Changes a signum of a double to that of an other double.

The returned value will have the same absolute value as the first argument and the same signum as the second argument. If the first argument is NaN, then the returned value will be NaN, if the second argument is NaN, then the behaviour is undefined.

Parameters:

	a	The number of the absolute value is used
	b	The number of which the signum is used

Returns:

A value that has the absolute value of a and the signum of b.

float copysignf	(	float	a,
		float	b
	)

Changes a signum of a double to that of an other double.

The returned value will have the same absolute value as the first argument and the same signum as the second argument. If the first argument is NaN, then the returned value will be NaN, if the second argument is NaN, then the behaviour is undefined.

Parameters:

	a	The number of the absolute value is used
	b	The number of which the signum is used

Returns:

A value that has the absolute value of a and the signum of b.

double fabs

(

double

d

)

Absolute value of a double-precision float-point number.

The function returns the absolute value of a double. If the argument is NAN the returned value is NAN, otherwise the returned value is the same as the argument with its signum changed to positive.

Parameters:

d

The value of which the absolute value should be calculated

Returns:

The absolute value of d.

float fabsf

(

float

f

)

Absolute value of a single-precision float-point number.

The function returns the absolute value of a float. If the argument is NAN the returned value is NAN, otherwise the returned value is the same as the argument with its signum changed to positive.

Parameters:

f

The value of which the absolute value should be calculated

Returns:

The absolute value of f.

double floor

(

double

x

)

Rounds a number down to the nearest integer.

If the argument is infinite, NaN, zero or a value that represents an integer, then the value is returned as it is. For all other values the value representing the largest integer that is not larger than the argument is returned. That is, for positive numbers the fractional part is simply discarded, for negative numbers the fractional part is discarded and 1 is subtracted from the number. E.g. 2.5 will change to 2.0 but -2.5 will be changed to -3.0.

Parameters:

x

The number to calculate the floor of

Returns:

The floor of x, or x if x is already an integer, is infinite, is zero or is not a number.

float floorf

(

float

x

)

Rounds a number down to the nearest integer.

If the argument is infinite, NaN, zero or a value that represents an integer, then the value is returned as it is. For all other values the value representing the largest integer that is not larger than the argument is returned. That is, for positive numbers the fractional part is simply discarded, for negative numbers the fractional part is discarded and 1 is subtracted from the number. E.g. 2.5 will change to 2.0 but -2.5 will be changed to -3.0.

Parameters:

x

The number to calculate the floor of

Returns:

The floor of x, or x if x is already an integer, is infinite, is zero or is not a number.

double frexp	(	double	x,
		int *	p
	)

Splits a double number to a double mantissa and an integer exponent.

The function decomposes its first argument x to a pair of a float-point m and an integer e so that the following is true:

x = m * 2e
0.5 <= |m| < 1.0

Them it stores e by the location pointed by the second argument and return m.

Parameters:

	x	The double that should be split
	p	Pointer to an integer that will hold the exponent

Return values:

	NaN	if the argument was NaN, *p is set to 0x80000000
	INF	if the argument was infinite, *p is set 0x7fffffff
	0	if the argument was zero, *p is set to 0
	+/-[0.5,1.0)	otherwise, *p is set so that return value * 2*p is the argument x.

float frexpf	(	float	x,
		int *	p
	)

Splits a float number to a float mantissa and an integer exponent.

The function decomposes its first argument x to a pair of a float-point m and an integer e so that the following is true:

x = m * 2e
0.5 <= |m| < 1.0

Them it stores e by the location pointed by the second argument and return m.

Parameters:

	x	The float that should be split
	p	Pointer to an integer that will hold the exponent

Return values:

	NaN	if the argument was NaN, *p is set to 0x80000000
	INF	if the argument was infinite, *p is set 0x7fffffff
	0	if the argument was zero, *p is set to 0
	+/-[0.5,1.0)	otherwise, *p is set so that return value * 2*p is the argument x.

double infinity

(

void

)

Returns positive infinity.

Returns:

Positive infinity

float infinityf

(

void

)

Returns positive infinity.

Returns:

Positive infinity

double ldexp	(	double	x,
		int	p
	)

Multiplies a double with an integer power of 2.

The function takes the float-point number x and the integer p and returns x * 2p.

Parameters:

	x	The double to be multiplied
	p	The integer power of 2

Return values:

	NaN	if x was NaN
	0.0	if x was 0 or if p is such a large negative number that the result can not be represented in a double
	INF	if x was infinity or if p is such a large positive number that the result can not be represented in a double
	x*2^p	otherwise

float ldexpf	(	float	x,
		int	p
	)

Multiplies a float with an integer power of 2.

The function takes the float-point number x and the integer p and returns x * 2p.

Parameters:

	x	The float to be multiplied
	p	The integer power of 2

Return values:

	NaN	if x was NaN
	0.0	if x was 0 or if p is such a large negative number that the result can not be represented in a float
	INF	if x was infinity or if p is such a large positive number that the result can not be represented in a float
	x*2^p	otherwise

double modf	(	double	x,
		double *	i
	)

Extracts the signed integral and fractional parts of a number.

If the argument x is NaN or infinite, then NaN is returned and the location pointed by the i argument is untouched. Otherwise the integer part (as obtained by the trunc() function) of x is stored at the location pointed by i and x minus the stored value (that is, the fractional part of the number) is returned. The signum of the integral and fractional parts is the same as that of the x argument, as long as the value is nonzero. If either the stored or the returned value is 0, then the signum of that 0 is not guaranteed to match the signum of x.

Parameters:

	x	The number to decompose to integer and fractional parts
	i	Pointer to a location where the integer part will be stored. If the pointer is NULL, then the integer part will be discarded.

Returns:

NaN if the x argument was NaN or infinite, the signed fractional part of x otherwise.

float modff	(	float	x,
		float *	i
	)

Extracts the signed integral and fractional parts of a number.

If the argument x is NaN or infinite, then NaN is returned and the location pointed by the i argument is untouched. Otherwise the integer part (as obtained by the trunc() function) of x is stored at the location pointed by i and x minus the stored value (that is, the fractional part of the number) is returned. The signum of the integral and fractional parts is the same as that of the x argument, as long as the value is nonzero. If either the stored or the returned value is 0, then the signum of that 0 is not guaranteed to match the signum of x.

Parameters:

	x	The number to decompose to integer and fractional parts
	i	Pointer to a location where the integer part will be stored. If the pointer is NULL, then the integer part will be discarded.

Returns:

NaN if the x argument was NaN or infinite, the signed fractional part of x otherwise.

double nan

(

const char *

unused

)

Return a not-a-number.

This function returns a non-signalling NaN. It has a parameter, which by the standard should be a string, describing what sort of a NaN it is. This library uses a fixed NaN pattern, namely setting every bit to 1. There is no formal specification for the meaning of the bits for a NaN, except one, which should be cleared for a signalling NaN and set for a quiet NaN. Since the library supports only quiet NaNs, this bit, together will all unspecified qualifier bits, is set.

Parameters:

unused

An unspecified qualifier for the NaN, not used by the function.

Returns:

A non-signalling NaN

float nanf

(

const char *

unused

)

Return a not-a-number.

This function returns a non-signalling NaN. It has a parameter, which by the standard should be a string, describing what sort of a NaN it is. This library uses a fixed NaN pattern, namely setting every bit to 1. There is no formal specification for the meaning of the bits for a NaN, except one, which should be cleared for a signalling NaN and set for a quiet NaN. Since the library supports only quiet NaNs, this bit, together will all unspecified qualifier bits, is set.

Parameters:

unused

An unspecified qualifier for the NaN, not used by the function.

Returns:

A non-signalling NaN

double round

(

double

x

)

Round a number to the nearest integer.

The function returns a double that represents the integer closest to its argument. If the fractional part of the argument is exactly 0.5, then the integer further away from 0 is returned.

The argument is returned unchanged if it was NaN or its absolute value was larger than 2⁵³; positive 0 is returned if the absolute value of the argument was less than 0.5 and the rounding result is returned otherwise.

Parameters:

x

The number to be rounded

Returns:

The rounded value

float roundf

(

float

x

)

Round a number to the nearest integer.

The function returns a float that represents the integer closest to its argument. If the fractional part of the argument is exactly 0.5, then the integer further away from 0 is returned.

The argumen is returned unchanged if it was NaN or its absolute value was larger than 2²⁴; positive 0 is returned if the absolute value of the argument was less than 0.5 and the rounding result is returned otherwise.

Parameters:

x

The number to be rounded

Returns:

The rounded value

double trunc

(

double

x

)

Truncate the number to the next integer towards zero.

The function returns a double that represents the integer that has an absolute value not larger than the that of the argument and is closest to its argument. That is, it simply discards all fractional bits of the argument. The function returns the argument if it was NaN or its absolute value was larger than 2⁵³; returns positive 0 if the absolute value of the argument was less than 1.0 and the truncated value otherwise.

Parameters:

x

The number to be truncated

Returns:

The truncated value

float truncf

(

float

x

)

Truncate the number to the next integer towards zero.

The function returns a float that represents the integer that has an absolute value not larger than the that of the argument and is closest to its argument. That is, it simply discards all fractional bits of the argument. The function returns the argument if it was NaN or its absolue value was larger than 2²⁴; returns positive 0 if the absolute value of the argument was less than 1.0 and the truncated value otherwise.

Parameters:

x

The number to be truncated

Returns:

The truncated value