# Elementary functions
[Float-point functions]

This is a library of the most frequently used transcendental functions. More...

## Functions
double | sqrt (double x)
| Square root function.
float | sqrtf (float x)
| Square root function.
double | acosh (double x)
| Inverse hyperbolic cosine function.
float | acoshf (float x)
| Inverse hyperbolic cosine function.
double | asin (double x)
| Arcus sine function.
double | acos (double x)
| Arcus cosine function.
float | asinf (float x)
| Arcus sine function.
float | acosf (float x)
| Arcus cosine function.
double | asinh (double x)
| Inverse hyperbolic sine function.
float | asinhf (float x)
| Inverse hyperbolic sine function.
double | atan (double x)
| Arcus tangent function.
double | atan2 (double y, double x)
| Quadrant correct arcus tangent function.
float | atan2f (float y, float x)
| Quadrant correct arcus tangent function.
float | atanf (float x)
| Arcus tangent function.
double | atanh (double x)
| Inverse hyperbolic tangent function.
float | atanhf (float x)
| Inverse hyperbolic tangent function.
double | cosh (double x)
| Hyperbolic cosine function.
float | coshf (float x)
| Hyperbolic cosine function.
double | exp2 (double x)
| Power of two function.
double | exp10 (double x)
| Power of ten function.
double | exp (double x)
| Inverse natural logarithm function.
float | exp2f (float x)
| Power of two function.
float | exp10f (float x)
| Power of ten function.
float | expf (float x)
| Inverse natural logarithm function.
double | log2 (double x)
| Base-2 logarithm function.
double | log (double x)
| Natural logarithm function.
double | log10 (double x)
| Base-10 logarithm function.
float | log2f (float x)
| Base-2 logarithm function.
float | logf (float x)
| Natural logarithm function.
float | log10f (float x)
| Base-10 logarithm function.
double | polynom (double x, const double *c, unsigned n)
| Evaluate a polynom.
float | polynomf (float x, const float *c, unsigned n)
| Evaluate a polynom.
double | sin (double x)
| Sine function.
double | cos (double x)
| Cosine function.
float | sinf (float x)
| Sine function.
float | cosf (float x)
| Cosine function.
double | sinh (double x)
| Hyperbolic sine function.
float | sinhf (float x)
| Hyperbolic sine function.
double | tan (double x)
| Tangent function.
double | cot (double x)
| Cotangent function.
float | tanf (float x)
| Tangent function.
float | cotf (float x)
| Cotangent function.
double | tanh (double x)
| Hyperbolic tangent function.
float | tanhf (float x)
| Hyperbolic tangent function.

## Detailed Description

This is a library of the most frequently used transcendental functions.

Both `float` and `double` versions are provided.
These functions spend most of their time inside the float-point arithmetic library that comes with gcc. That library is written in assembly, therefore the execution time of these functions depends very little on whether you compile them for ARM or for THUMB.
Functions called with invalid arguments will return a non-sgnalling NaN. There is no other indication of the problem, no facility is provided for you to set up an exception handler to catch float-point errors. If you need it, you have to explicitely check the result of the calculations for NaN and raise the exception yourself.
NaN-s are propagated, therefore on a long calculation chain, if anywhere in the chain any result was NaN, the end result is also guaranteed to be NaN.
The functions are fairly accurate, but not last-bit accurate. If the last bit precision would have costed significant amount of runtime, I opted for the faster version. This means that the transcendental functions can produce a relative error up to around to 1E-16 for `doubles` and about 5E-7 for `floats`. In addition, while the `double` version of the trigonometric functions have proper range reduction, giving you the real result even if you calculate for example `sin(1E200)`, the `float` version uses a much simpler (and faster) range reduction method, that is fairly accurate up to 1E8. Rather than giving you results that are way off, for arguments over 1E8 the `float` trigonometric functions will return NaN-s.
The execution time for some of these functions can be found in the table below, they were measured on an LPC23xx chip running at 60MHz. Furthermore, the time needed for the basic float point arithmetic operations (that is, the routines in gcc's float library) is also provided for reference.

                Execution time of some float-point functions [µs]

    Function   +     *     /     sqrt     sin   asin    tan   atan    exp    log
    float     1.0   0.9   2.6     2.1      17     26     23     29     20     26
    double    1.8   1.7  10.5    10.8      36     66     55     70     43     56

## Function Documentation

double acos | ( | double | x | ) |

Arcus cosine function.

Parameters:

  | x | The value of which the arcus cosine should be calculated

Return values:

  | NaN | The argument was NaN or outside of [-1.0,+1.0].
  | acos(x) | Otherwise. The returned value is in radian and in the principal range of [0,PI]

float acosf | ( | float | x | ) |

Arcus cosine function.

Parameters:

  | x | The value of which the arcus cosine should be calculated

Return values:

  | NaN | The argument was NaN or outside of [-1.0,+1.0].
  | acos(x) | Otherwise. The returned value is in radian and in the principal range of [0,PI]

double acosh | ( | double | x | ) |

Inverse hyperbolic cosine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN or less than +1.0
  | +INF | The argument was infinite
  | acosh(x) | Otherwise, always the positive x is returned.

float acoshf | ( | float | x | ) |

Inverse hyperbolic cosine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN or less than +1.0
  | +INF | The argument was infinite
  | acosh(x) | Otherwise, always the positive x is returned.

double asin | ( | double | x | ) |

Arcus sine function.

Parameters:

  | x | The value of which the arcus sine should be calculated

Return values:

  | NaN | The argument was NaN or outside of [-1.0,+1.0].
  | asin(x) | Otherwise. The returned value is in radian and in the principal range of [-PI/2,+PI/2]

float asinf | ( | float | x | ) |

Arcus sine function.

Parameters:

  | x | The value of which the arcus sine should be calculated

Return values:

  | NaN | The argument was NaN or outside of [-1.0,+1.0].
  | asin(x) | Otherwise. The returned value is in radian and in the principal range of [-PI/2,+PI/2]

double asinh | ( | double | x | ) |

Inverse hyperbolic sine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | INF | The argument was infinite
  | asinh(x) | Otherwise

float asinhf | ( | float | x | ) |

Inverse hyperbolic sine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | INF | The argument was infinite
  | asinh(x) | Otherwise

double atan | ( | double | x | ) |

Arcus tangent function.

Parameters:

  | x | The value of which the arcus tangent should be calculated

Return values:

  | NaN | The argument was NaN
  | +PI/2 | The argument was positive infinity
  | -PI/2 | The argument was negative infinity
  | atan(x) | Otherwise. The returned value is in radian and in the principal range of [-PI/2,+PI/2].

double atan2 | ( | double | y,
|  | double | x |
| ) |  |  |

Quadrant correct arcus tangent function.

The function returns the angle between the positive x axis and the hypothenuse of a triangle formed by the (0,0) (x,0) (x,y) points. The returned angle is in [-PI, +PI].

Parameters:

  | x | The X coordinate of the end point of the hypothenuse
  | y | The Y coordinate of the end point of the hypothenuse

Return values:

  | NaN | Either x or y was NaN, they were both infinite or they were both zero.
  | atan(y/x) | Otherwise; with the range extended to cover a full circle, depending on the signum of y and x.

float atan2f | ( | float | y,
|  | float | x |
| ) |  |  |

Quadrant correct arcus tangent function.

The function returns the angle between the positive x axis and the hypothenuse of a triangle formed by the (0,0) (x,0) (x,y) points. The returned angle is in [-PI, +PI].

Parameters:

  | x | The X coordinate of the end point of the hypothenuse
  | y | The Y coordinate of the end point of the hypothenuse

Return values:

  | NaN | Either x or y was NaN, they were both infinite or they were both zero.
  | atan(y/x) | Otherwise; with the range extended to cover a full circle, depending on the signum of y and x.

float atanf | ( | float | x | ) |

Arcus tangent function.

Parameters:

  | x | The value of which the arcus tangent should be calculated

Return values:

  | NaN | The argument was NaN
  | +PI/2 | The argument was positive infinity
  | -PI/2 | The argument was negative infinity
  | atan(x) | Otherwise. The returned value is in radian and in the principal range of [-PI/2,+PI/2].

double atanh | ( | double | x | ) |

Inverse hyperbolic tangent function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN or not in [-1,+1].
  | +INF | The argument was +1
  | -INF | The argument was -1
  | atanh(x) | Otherwise

float atanhf | ( | float | x | ) |

Inverse hyperbolic tangent function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN or not in [-1,+1].
  | +INF | The argument was +1
  | -INF | The argument was -1
  | atanh(x) | Otherwise

double cos | ( | double | x | ) |

Cosine function.

Parameters:

  | x | The value to calculate the cosine of, in radians

Return values:

  | NaN | The argument was NaN or infinite
  | cos(x) | Otherwise

float cosf | ( | float | x | ) |

Cosine function.

Parameters:

  | x | The value to calculate the cosine of, in radians

Return values:

  | NaN | The argument was NaN or outside of the range of +/- 1E8.
  | cos(x) | Otherwise

double cosh | ( | double | x | ) |

Hyperbolic cosine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was infinite or the result would overflow
  | cosh(x) | Otherwise

float coshf | ( | float | x | ) |

Hyperbolic cosine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was infinite or the result would overflow
  | cosh(x) | Otherwise

double cot | ( | double | x | ) |

Cotangent function.

Parameters:

  | x | The value to calculate the cotangent of, in radians

Return values:

  | NaN | The argument was NaN
  | INF | The argument was very close to, but not exactly at, a value of k * PI where k is an integer, the signum of the infinity depends on which side of the singularity was x.
  | ctg(x) | Otherwise

Note:
  Since the IEEE-754 doubles can not represent irrational numbers, the argument to this function can never be an exact multiple of PI. Therefore, the function never returns NaN for a finite argument. There is one exception, namely 0. The 0.0 value is indeed representable in IEEE-754 and thus this function could return a NaN for that. However, this implementation returns + or - infinity, depending on the sign of the zero argument. If you rely on the function returning NaN on 0, you have to put a little wrapper around it.

float cotf | ( | float | x | ) |

Cotangent function.

Parameters:

  | x | The value to calculate the cotangent of, in radians

Return values:

  | NaN | The argument was NaN or outside of +/- 1E8.
  | INF | The argument was very close to (but not exactly at) a value of k * PI where k is an integer, the signum of the infinity depends on which side of the singularity was x.
  | ctg(x) | Otherwise

Note:
  Since the IEEE-754 floats can not represent irrational numbers, the argument to this function can never be an exact multiple of PI. Therefore, the function never returns NaN for a finite argument. There is one exception, namely 0. The 0.0 value is indeed representable in IEEE-754 and thus this function could return a NaN for that. However, this implementation returns + or - infinity, depending on the sign of the zero argument. If you rely on the function returning NaN on 0, you have to put a little wrapper around it.

double exp | ( | double | x | ) |

Inverse natural logarithm function.

Parameters:

  | x | The power to which 'e' should be raised

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | 0.0 | The argument was -INF or the result would underflow
  | e^x | Otherwise

double exp10 | ( | double | x | ) |

Power of ten function.

Parameters:

  | x | The power to which 10 should be raised

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | 0.0 | The argument was -INF or the result would underflow
  | 10^x | Otherwise

float exp10f | ( | float | x | ) |

Power of ten function.

Parameters:

  | x | The power to which 10 should be raised

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | 0.0 | The argument was -INF or the result would underflow
  | 10^x | Otherwise

double exp2 | ( | double | x | ) |

Power of two function.

Parameters:

  | x | The power to which 2 should be raised

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | 0.0 | The argument was -INF or the result would underflow
  | 2^x | Otherwise

float exp2f | ( | float | x | ) |

Power of two function.

Parameters:

  | x | The power to which 2 should be raised

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | 0.0 | The argument was -INF or the result would underflow
  | 2^x | Otherwise

float expf | ( | float | x | ) |

Inverse natural logarithm function.

Parameters:

  | x | The power to which 'e' should be raised

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | 0.0 | The argument was -INF or the result would underflow
  | e^x | Otherwise

double log | ( | double | x | ) |

Natural logarithm function.

Parameters:

  | x | The number of which the logarithm should be computed

Return values:

  | NaN | The argument was NaN or negative, including negative zero
  | -INF | The argument was positive zero
  | +INF | The argument was positive infinity
  | ln(x) | Otherwise

double log10 | ( | double | x | ) |

Base-10 logarithm function.

Parameters:

  | x | The number of which the logarithm should be computed

Return values:

  | NaN | The argument was NaN or negative, including negative zero
  | -INF | The argument was positive zero
  | +INF | The argument was positive infinity
  | log10(x) | Otherwise

float log10f | ( | float | x | ) |

Base-10 logarithm function.

Parameters:

  | x | The number of which the logarithm should be computed

Return values:

  | NaN | The argument was NaN or negative, including negative zero
  | -INF | The argument was positive zero
  | +INF | The argument was positive infinity
  | log10(x) | Otherwise

double log2 | ( | double | x | ) |

Base-2 logarithm function.

Parameters:

  | x | The number of which the logarithm should be computed

Return values:

  | NaN | The argument was NaN or negative, including negative zero
  | -INF | The argument was positive zero
  | +INF | The argument was positive infinity
  | log2(x) | Otherwise

float log2f | ( | float | x | ) |

Base-2 logarithm function.

Parameters:

  | x | The number of which the logarithm should be computed

Return values:

  | NaN | The argument was NaN or negative, including negative zero
  | -INF | The argument was positive zero
  | +INF | The argument was positive infinity
  | log2(x) | Otherwise

float logf | ( | float | x | ) |

Natural logarithm function.

Parameters:

  | x | The number of which the logarithm should be computed

Return values:

  | NaN | The argument was NaN or negative, including negative zero
  | -INF | The argument was positive zero
  | +INF | The argument was positive infinity
  | ln(x) | Otherwise

double polynom | ( | double | x,
|  | const double * | c,
|  | unsigned | n |
| ) |  |  |

Evaluate a polynom.

This function evaluates a polynom, that is, it calculates the sum of
`SUM( Ci * xi )`
where `i` goes from 0 to `n` (inclusive), `x` is a variable, `ci` is the i-th coefficient and `n` is the order of the polynom.
The function uses the Horner scheme, performing n multiplcations and n additions.

Parameters:

  | x | The place where the polynom should be evaluated.
  | c | Pointer to an array containing the coefficients. The array must have `n+1` elements and the array index corresponds to the index of the coefficient.
  | n | The order of the polynom. 0 is a valid value.

Returns:
  The value of the polynom determined by `c` and `n`, at the point of `x`.

float polynomf | ( | float | x,
|  | const float * | c,
|  | unsigned | n |
| ) |  |  |

Evaluate a polynom.

This function evaluates a polynom, that is, it calculates the sum of
`SUM( Ci * xi )`
where `i` goes from 0 to `n` (inclusive), `x` is a variable, `ci` is the i-th coefficient and `n` is the order of the polynom.
The function uses the Horner scheme, performing n multiplications and n additions.

Parameters:

  | x | The place where the polynom should be evaluated.
  | c | Pointer to an array containing the coefficients. The array must have `n+1` elements and the array index corresponds to the index of the coefficient.
  | n | The order of the polynom. 0 is a valid value.

Returns:
  The value of the polynom determined by `c` and `n`, at the point of `x`.

double sin | ( | double | x | ) |

Sine function.

Parameters:

  | x | The value to calculate the sine of, in radians

Return values:

  | NaN | The argument was NaN or infinite
  | sin(x) | Otherwise

float sinf | ( | float | x | ) |

Sine function.

Parameters:

  | x | The value to calculate the sine of, in radians

Return values:

  | NaN | The argument was NaN or outside of the range of +/- 1E8.
  | sin(x) | Otherwise

double sinh | ( | double | x | ) |

Hyperbolic sine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | -INF | The argument was -INF or the result would overflow
  | sinh(x) | Otherwise

float sinhf | ( | float | x | ) |

Hyperbolic sine function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | +INF | The argument was +INF or the result would overflow
  | -INF | The argument was -INF or the result would overflow
  | sinh(x) | Otherwise

double sqrt | ( | double | x | ) |

Square root function.

The function calculates the square root of its argument. If the argument is NaN or negative, NaN is returned. Negative 0 is accepted and the returned value is positive 0. If the argument is positive infinity, then positive infinity is returned. Otherwise, the square root of the argument is returned.

Parameters:

  | x | The number of which the square root is to be calculated

Return values:

  | NaN | The argument was NaN or a non-zero negative number
  | +INF | The argument was positive infinity
  | +0 | The argument was +0 or -0
  | sqrt(x) | Otherwise

float sqrtf | ( | float | x | ) |

Square root function.

The function calculates the square root of its argument. If the argument is NaN or negative, NaN is returned. Negative 0 is accepted and the returned value is positive 0. If the argument is positive infinity, then positive infinity is returned. Otherwise, the square root of the argument is returned.

Parameters:

  | x | The number of which the square root is to be calculated

Return values:

  | NaN | The argument was NaN or a non-zero negative number
  | +INF | The argument was positive infinity
  | +0 | The argument was +0 or -0
  | sqrt(x) | Otherwise

double tan | ( | double | x | ) |

Tangent function.

Parameters:

  | x | The value to calculate the tangent of, in radians

Return values:

  | NaN | The argument was NaN.
  | INF | The argument was very close to (but not exactly at) a value of PI/2 + k * PI where k is an integer, the signum of the infinity depends on which side of the singularity was x.
  | tg(x) | Otherwise

float tanf | ( | float | x | ) |

Tangent function.

Parameters:

  | x | The value to calculate the tangent of, in radians

Return values:

  | NaN | The argument was NaN or outside of +/- 1E8.
  | INF | The argument was very close to (but not exactly at) a value of PI/2 + k * PI where k is an integer, the signum of the infinity depends on which side of the singularity was x.
  | tg(x) | Otherwise

double tanh | ( | double | x | ) |

Hyperbolic tangent function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | +1 | The argument was +INF
  | -1 | The argument was -INF
  | tanh(x) | Otherwise

float tanhf | ( | float | x | ) |

Hyperbolic tangent function.

Parameters:

  | x | The function argument

Return values:

  | NaN | The argument was NaN
  | +1 | The argument was +INF
  | -1 | The argument was -INF
  | tanh(x) | Otherwise