# 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 253; 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 224; 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 253; 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 224; 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