The <math.h> header file
This header file contains the following functions:
abs acos acosh asin
asinh atan atan2 atanh
atof cacos cacosh casin
casinh catan catanh ccos
ccosh ceil cexp cln
clog10 cos cosh csin
csinh csqrt ctan ctanh
exp fabs floor fmod
frexp10 hypot is_inf is_nan
is_nzero is_pzero is_sinf is_transfinite
is_uinf_or_nan is_uzero labs ldexp10
log log10 modf pow
sin sinh sqrt tan
tanh
and the following constants and predefined types:
Bool HALF_PI NAN NEGATIVE_INF
NEGATIVE_ZERO PI POSITIVE_INF POSITIVE_ZERO
UNSIGNED_INF UNSIGNED_ZERO ZERO
NOTE: all functions which return a result of float
type are
implemented as macros, although many of them exists as TIOS entries. This is done
because GCC convention of returning floating point values as a result of a function is
different than the convention expected by TIOS. This note is mainly unimportant from
the user point of view. Also note that timath.h header file
contains all functions from math.h, but in addition to this, it also contains some
very TIOS-specific low-level floating point functions.
Functions
Absolute value of a number.
abs returns the absolute value of a numeric argument x, which may be either an integer
or a floating point value. The returned value is of the same type as the argument.
See also labs and fabs.
NOTE: abs is a smart macro which compiles to an open code, which depends of the type of the
argument.
Absolute value of a long integer number.
labs returns the absolute value of (long) integer argument x.
See also abs and fabs.
NOTE: labs is built-in function in GCC compiler itself, and it compiles to the open code
instead of function call.
float fabs (float x);
Absolute value of a floating point number.
fabs returns the absolute value of floating point argument x.
See also abs and labs.
float sqrt (float x);
Floating point square root.
sqrt returns the positive square root of floating point argument x.
NOTE: If the argument is negative, there will be no error, but the result
will be invalid.
float exp (float x);
Floating point exponential function.
exp returns the exponential function of floating point argument x
(i.e. calculates e to the x-th power).
NOTE: exp will return POSITIVE_INF in a case of overflow, and
zero (unsigned, see ZERO; strange, I expected
POSITIVE_ZERO) in a case of underflow.
float log (float x);
Floating point natural logarithm (base e).
log returns the natural logarithm of floating point argument x.
NOTE: log will return NEGATIVE_INF if the argument is
zero, or NAN if the argument is negative.
float log10 (float x);
Floating point logarithm, base 10.
log10 returns the base 10 logarithm of floating point argument x.
NOTE: log will return NEGATIVE_INF if the argument is
zero, or NAN if the argument is negative.
float pow (float x, float y);
Floating point power function.
pow returns x^y, x to the y (i.e. x raised to the
y-th power).
NOTE: pow will return an infinite result (see POSITIVE_INF,
NEGATIVE_INF, UNSIGNED_INF)
in a case of overflow. If both x and y are zeros, pow will return 1.
If x is negative, the correct result will be produced only if y can
be represented as a whole number, or as a fraction with odd denominator; otherwise,
pow will return a garbage (not NAN) which sometimes even not
satisfy the floating point BCD format (digits greater than 9 etc.), so be careful in
a case when x is negative!
float sin (float x);
Floating point sine.
sin returns the sine of floating point argument x, which is assumed
to be specified in radians.
NOTE: sin will return NAN if the argument is so big that
reducing to the main period can't be performed without complete losing of
significant digits (i.e. when the magnitude of x is greater than 1e13).
float cos (float x);
Floating point cosine.
cos returns the cosine of floating point argument x, which is assumed
to be specified in radians.
NOTE: cos will return NAN if the argument is so big that
reducing to the main period can't be performed without complete losing of
significant digits (i.e. when the magnitude of x is greater than 1e13).
float tan (float x);
Floating point tangent.
tan returns the tangent of floating point argument x, which is assumed
to be specified in radians.
NOTE: tan will return UNSIGNED_INF for all arguments
for which the tangent is infinity. Also, it will return NAN if the
argument is so big that reducing to the main period can't be performed without
complete losing of significant digits (i.e. when the magnitude of x is
greater than 1e13).
float asin (float x);
Floating point arc sine.
asin returns the arc sine of floating point argument x. The result is
always in radians.
NOTE: If the argument is not in range from -1 to 1, asin will return
NAN.
float acos (float x);
Floating point arc cosine.
acos returns the arc cosine of floating point argument x. The result is
always in radians.
NOTE: If the argument is not in range from -1 to 1, acos will return
NAN.
float atan (float x);
Floating point arc tangent.
asin returns the arc tangent of floating point argument x. The result is
always in radians.
float atan2 (float x, float y);
Four-quadrant arc tangent of y/x (or argument of the complex number).
atan2 returns the four-quadrant arc tangent of y/x. More precise,
it returns the argument of the complex number x + y i.
So, the result is in the range -pi to pi.
NOTE: atan2 produces correct results even when the
resulting angle is near pi/2 or -pi/2 (x near
zero). If both x and y are zeros, atan2 returns NAN.
float sinh (float x);
Floating point hyperbolic sine.
sinh returns the hyperbolic sine of floating point argument x.
Hyperbolic sine is defined as (exp(x)-exp(-x))/2.
NOTE: sinh will return POSITIVE_INF or
NEGATIVE_INF in a case of overflow.
float cosh (float x);
Floating point hyperbolic cosine.
sinh returns the hyperbolic cosine of floating point argument x.
Hyperbolic cosine is defined as (exp(x)+exp(-x))/2.
NOTE: cosh will return POSITIVE_INF
in a case of overflow.
float tanh (float x);
Floating point hyperbolic tangent.
sinh returns the hyperbolic cosine of floating point argument x.
Hyperbolic tangent is defined as sinh(x)/cosh(x).
float asinh (float x);
Floating point hyperbolic area sine.
asinh returns the hyperbolic area sine of floating point argument x.
Hyperbolic area sine is defined as log(x+sqrt(x*x+1)).
float acosh (float x);
Floating point hyperbolic area cosine.
asinh returns the hyperbolic area cosine of floating point argument x,
Hyperbolic area cosine is defined as log(x+sqrt(x*x-1)).
NOTE: acosh will return NAN if x is smaller than 1.
float atanh (float x);
Floating point hyperbolic area tangent.
atanh returns the hyperbolic area tangent of floating point argument x,
Hyperbolic area tangent is defined as log((1+x)/(1-x))/2.
NOTE: asinh will return NAN if x is smaller than -1
or greather than 1. Also, it will return POSITIVE_INF
if x is 1, and NEGATIVE_INF if x is -1.
float ceil (float x);
Rounds up the floating point number.
ceil finds the smallest integer not less than floating point argument x,
and returns the integer found as a floating point value.
float floor (float x);
Rounds down the floating point number.
floor finds the largest integer not greater than floating point argument x,
and returns the integer found as a floating point value.
float fmod (float x, float y);
Calculates x modulo y, i.e. the remainder of x/y.
fmod returns x modulo y, i.e. it returns the remainder f, where
x = a * y + f for some integer a
and 0 <= f < y. Where y = 0, fmod returns 0.
float hypot (float x, float y);
Calculates hypotenuse of right triangle.
hypot returns the value z where z^2 = x^2 + y^2 and
z >= 0. This is equivalent to the length of the hypotenuse of a right
triangle, if the lengths of the two sides are x and y. Or, this
is also equivalent to the absolute value of the complex number
x + y i.
NOTE: hypot is implemented as macro which calls fmul (for squaring
x and y), fadd and sqrt.
float modf (float x, float *ipart);
Splits floating point value into integer and fraction part.
modf breaks the floating point value x into two parts: the integer and the
fraction, both having the same sign as x. It stores the integer in a floating point
destination pointed to by
ipart and returns the fractional part of x.
float frexp10 (float x, short *exponent);
Splits floating point number into mantissa and exponent.
frexp10 calculates the mantissa m (a floating point greater than or
equal to 0.1 and less than 1) and the integer value n, such that x
equals m*10^n. frexp stores n in the integer that exponent
points to, and returns the mantissa m.
NOTE: This routine is analogous to frexp
in ANSI C math library, except
using base ten rather than base two.
float ldexp10 (float x, short exponent);
Calculates x times 10 raised to exponent.
ldexp10 calculates x times 10 raised to exponent, and returns the
result, i.e. returns x*10^exponent. Strictly speaking, ldexp10 is
a macro, not a function.
NOTE: This routine is analogous to ldexp
in ANSI C math library, except
using base ten rather than base two.
float atof (const char *s);
Converts a string to a floating point.
atof converts a string pointed to by s to floating point value. It recognizes
the character representation of a floating point number, made up of the following:
- an optional string of spaces;
- an optional minus sign;
- a string of ditits and an optional decimal point (the digits can be on both
sides of the decimal point);
- an optional exponent followed by a (optionally signed) integer.
It is important to say that this implementation of atof requires that an optional
minus sign and an optional exponent must be TI Basic characters for minus sign and exponent,
(characters with codes 0xAD and 0x95 instead of ordinary
'-' and 'e' or 'E' characters).
This limitation is caused by using some TIOS calls which needs such number format. Anyway,
it is very easy to "preprocess" any string to satisfy this convention before calling to
atof by routine like the following (assuming that c is a char variable, and i
is an integer variable):
for (i = 0; c = s[i]; i++) // Yes, the second '=' is really '=', not '=='...
{
if (c == '-') s[i] = 0xAD;
if ((c|32) == 'e') s[i] = 0x95;
}
atof returns the converted value of the input string. It returns NAN if the
input string cannot be converted (i.e. if it is not in a correct format). This is not the same
as in ANSI C: atof in ANSI C returns 0 if the conversion was not successful. I decided to
return NAN instead, so the user can check whether the conversion was
successful (which is not possible with ANSI atof). See is_nan for a good
method to check whether the result is NAN.
NOTE: This function is not part of TIOS, and it is implemented
using TIOS function push_parse_text.
void csqrt (float z_re, float z_im, float *w_re, float *w_im);
Complex square root.
csqrt calculates the square root w = sqrt(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex square root is defined by
sqrt(z) = sqrt(abs(z)) (cos(arg(z)/2) + i sin(arg(z)/2))
where abs(z) = sqrt(z_re^2+z_im^2) and arg(z) = atan2(z_im, z_re).
See sqrt, atan2,
sin and cos.
void cexp (float z_re, float z_im, float *w_re, float *w_im);
Complex exponential function.
cexp calculates the complex exponential function w = exp(z) of the complex
number which real and imaginary parts are z_re and
z_im, and stores real and imaginary part of the result
in floating point destinations pointed to by w_re and
w_im. The complex exponential function is defined by
exp(z) = exp(z_re) (cos(z_im) + i sin(z_im))
See exp, sin and cos.
void cln (float z_re, float z_im, float *w_re, float *w_im);
Complex natural logarithm (base e).
cln calculates the natural logarithm w = ln(z) of the complex
number which real and imaginary parts are z_re and
z_im, and stores real and imaginary part of the result
in floating point destinations pointed to by w_re and
w_im. The complex logarithm is defined by
ln(z) = log(abs(z)) + i arg(z)
where abs(z) = sqrt(z_re^2+z_im^2), arg(z) = atan2(z_im, z_re)
and log is the real natural logarithm. See
also sqrt and atan2.
void clog10 (float z_re, float z_im, float *w_re, float *w_im);
Complex logarithm, base 10.
clog10 calculates the base 10 logarithm w = log10(z) of the complex
number which real and imaginary parts are z_re and
z_im, and stores real and imaginary part of the result
in floating point destinations pointed to by w_re and
w_im. The base 10 complex logarithm is defined by
log10(z) = ln(z) / ln(10)
where ln is complex natural logarithm
(see cln).
void csin (float z_re, float z_im, float *w_re, float *w_im);
Complex sine.
csin calculates the sine w = sin(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex sine is defined by
sin(z) = (exp(i z) - exp(-i z)) / (2 i)
where exp is complex exponential function
(see cexp).
void ccos (float z_re, float z_im, float *w_re, float *w_im);
Complex cosine.
ccos calculates the cosine w = cos(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex cosine is defined by
sin(z) = (exp(i z) + exp(-i z)) / 2
where exp is complex exponential function
(see cexp).
void ctan (float z_re, float z_im, float *w_re, float *w_im);
Complex tangent.
ctan calculates the tangent w = tan(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex tangent is defined by
tan(z) = sin(z) / cos(z)
where sin and cos are complex sine and
complex cosine (see csin and ccos).
void casin (float z_re, float z_im, float *w_re, float *w_im);
Complex arc sine.
casin calculates the arc sine w = asin(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex arc sine is defined by
asin(z) = -i ln (i z + sqrt (1 - z^2))
where ln and sqrt are complex natural
logarithm and complex square root (see cln and
csqrt).
void cacos (float z_re, float z_im, float *w_re, float *w_im);
Complex arc cosine.
cacos calculates the arc cosine w = acos(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex arc cosine is defined by
acos(z) = -i ln (z + i sqrt (1 - z^2))
where ln and sqrt are complex natural
logarithm and complex square root (see cln and
csqrt).
void catan (float z_re, float z_im, float *w_re, float *w_im);
Complex arc tangent.
catan calculates the arc tangent w = atan(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex arc tangent is defined by
atan(z) = -i ln ((1 + i z) / (1 - i z)) / 2
where ln is complex natural
logarithm (see cln).
void csinh (float z_re, float z_im, float *w_re, float *w_im);
Complex hyperbolic sine.
csinh calculates the hyperbolic sine w = sinh(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex hyperbolic sine is defined by
sinh(z) = (exp(z) - exp(-z)) / 2
where exp is complex exponential function
(see cexp).
void ccosh (float z_re, float z_im, float *w_re, float *w_im);
Complex hyperbolic cosine.
ccosh calculates the hyperbolic cosine w = cosh(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex hyperbolic cosine is defined by
cosh(z) = (exp(z) + exp(-z)) / 2
where exp is complex exponential function
(see cexp).
void ctanh (float z_re, float z_im, float *w_re, float *w_im);
Complex hyperbolic tangent.
ctanh calculates the hyperbolic tangent w = tanh(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex hyperbolic tangent is defined by
tanh(z) = sinh(z) / cosh(z)
where sinh and cosh are complex hyperbolic
sine and complex hyperbolic cosine (see csinh and
ccosh).
void casinh (float z_re, float z_im, float *w_re, float *w_im);
Complex hyperbolic area sine.
casinh calculates the hyperbolic area sine w = asinh(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex hyperbolic area sine is defined by
asinh(z) = ln (z + sqrt (z^2 + 1))
where ln and sqrt are complex natural
logarithm and complex square root (see cln and
csqrt).
void cacosh (float z_re, float z_im, float *w_re, float *w_im);
Complex hyperbolic area cosine.
cacosh calculates the hyperbolic area cosine w = acosh(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex hyperbolic area cosine is defined by
acosh(z) = ln (z + sqrt (z^2 - 1))
where ln and sqrt are complex natural
logarithm and complex square root (see cln and
csqrt).
void catanh (float z_re, float z_im, float *w_re, float *w_im);
Complex hyperbolic area tangent.
catanh calculates the hyperbolic area tangent w = atanh(z) of the complex number which real and
imaginary parts are z_re and z_im, and stores real and
imaginary part of the result in floating point destinations pointed to by
w_re and w_im. The complex hyperbolic area tangent is defined by
acosh(z) = ln ((1 + z) / (1 - z)) / 2
where ln is complex natural logarithm
(see cln).
short is_nan (float x);
Checks whether the argument is Not_a_Number.
is_nan returns TRUE if x is NAN
(Not_a_Number), else returns FALSE. Not_a_Number is a special
value which is produced as a result of all operations when the result is undefined
or non-real, for example dividing zero with zero, calculating the logarithm of
a negative number, etc.
short is_inf (float x);
Checks whether the argument is an infinite number.
is_inf returns TRUE if x is an infinite number
(i.e. UNSIGNED_INF, POSITIVE_INF
or NEGATIVE_INF), else returns FALSE.
Infinite values are produced when the result is unbounded (for example dividing by
zero), or in case of overflow.
short is_pzero (float x);
Checks whether the argument is positive zero.
is_pzero returns TRUE if x is a positive zero
(i.e. infinitely small positive quantity, see POSITIVE_ZERO), else returns FALSE.
short is_nzero (float x);
Checks whether the argument is negative zero.
is_nzero returns TRUE if x is a negative zero
(i.e. infinitely small negative quantity, see NEGATIVE_ZERO), else returns FALSE.
short is_uzero (float x);
Checks whether the argument is unsigned zero.
is_uzero returns TRUE if x is an unsigned zero
(i.e. infinitely small quantity with indeterminate sign, see UNSIGNED_ZERO),
else returns FALSE.
short is_sinf (float x);
Checks whether the argument is signed infinity.
is_sinf returns TRUE if x is a signed infinity
(i.e. POSITIVE_INF or NEGATIVE_INF),
else returns FALSE.
short is_uinf_or_nan (float x);
Checks whether the argument is unsigned infinity or Not_a_Number.
is_uinf_or_nan returns TRUE if x is
UNSIGNED_INF or NAN,
else returns FALSE. These two special numbers
are treated very similarly in TIOS.
short is_transfinite (float x);
Checks whether the argument is a transfinite number.
is_transfinite returns TRUE if x is
a transfinite number, else returns FALSE.
Transfinite numbers are all infinite numbers
(UNSIGNED_INF, POSITIVE_INF
and NEGATIVE_INF) and NAN.
Constants and predefined types
Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};
ZERO
is a predefined floating point constant with value 0.0
.
ZERO
is the same as UNSIGNED_ZERO.
PI
is a predefined floating point constant which approximates pi up
to 16 significant digits, i.e. 3.141592653589793
.
HALF_PI
is a predefined floating point constant which approximates pi/2 up to
16 significant digits, i.e. 1.570796326794897
.
Of course, it is the same as PI/2.0
.
TIOS makes a difference between three types of zeros. UNSIGNED_ZERO
is "ordinary" zero,
i.e. infinitely small quantity with indeterminate sign. It is identical to
ZERO. Dividing any finite non-zero number by UNSIGNED_ZERO
will produce
UNSIGNED_INF.
All kind of zeros are equal when comparing using comparison operators or fcmp. To check
whether a value is an unsigned zero, use is_uzero.
In opposite to UNSIGNED_ZERO, POSITIVE_ZERO
is an infinitely
small quantity which is known to be always nonnegative. It can be imagined as "the
smallest positive real number", altough something like this does not exist in reality.
TIOS generates POSITIVE_ZERO
in cases when the result is zero, but it is known that the
result can not be negative for any argument. For example, squaring of ZERO
using pow function will return POSITIVE_ZERO
, because the square is
always non-negative. The same is true for acosh when the argument
is equal to 1, etc.
TIOS also generates POSITIVE_ZERO
as the result of positive underflow (i.e. when the
result is positive, but too small to be represented in a float
type),
and as the result of rounding extremely small positive numbers using
round14 or round12_err.
To check whether a value is a positive zero, use is_pzero.
Dividing any finite strictly positive number by POSITIVE_INF
will produce POSITIVE_ZERO
as the result. Dividing any finite strictly positive number by
POSITIVE_ZERO gives POSITIVE_INF, and dividing any finite
strictly negative number by POSITIVE_ZERO
gives NEGATIVE_INF.
NOTE: Try in TI Basic '1/0'
and '1/0^2'
to see that
'0'
and '0^2'
are not strictly the same
for TIOS. Clever, isn't it?
NEGATIVE_ZERO
is similar like POSITIVE_ZERO, but it
represents an infinitely small quantity which is known to be always nonpositive.
The properties of NEGATIVE_ZERO
are analog to the properties of
POSITIVE_ZERO. To check whether a value is a negative
zero, use is_nzero.
POSITIVE_INF
represents an infinitely big positive quantity. TIOS generates POSITIVE_INF
when the result is infinite in magnitude, but when it is known to be positive (for example,
atanh returns POSITIVE_INF
when the argument is equal to 1). See also
POSITIVE_ZERO. TIOS also generates POSITIVE_INF
as the result of positive
overflow (i.e. when the result is positive and too big to be represented in
float
type), and as the result of rounding extremely big positive
numbers using round14 or round12_err.
TIOS allows much greater flexibility when working with "signed"
infinities than with UNSIGNED_INF. To check whether a value
is signed infinity, use is_sinf. POSITIVE_INF
belongs to the
class of "transfinite" numbers (see is_transfinite).
NEGATIVE_INF
represents an infinitely big positive quantity. TIOS generates
NEGATIVE_INF
when the result is infinite in magnitude, but when it is known to be negative (for example,
log returns NEGATIVE_INF
when the argument is equal to zero).
Other properties of NEGATIVE_INF
are analogous like properties of
POSITIVE_INF.
UNSIGNED_INF
represents a quantity for which is known to be infinite in magnitude, but
when nothing can be deduced about its sign. For example, dividing of non-zero number
with "standard" zero (i.e. with UNSIGNED_ZERO) or calculating
tangent of pi/2 will produce such value. TIOS mathematical functions are much
more limited in working with unsigned than with signed infinities (like
POSITIVE_INF). For example, arc tangent of POSITIVE_INF
is
well defined and equals to pi/2, but arc tangent of UNSIGNED_INF
is not unique determined.
Although UNSIGNED_INF
is much more "concrete"
quantity than NAN, TIOS very often does not make any difference
between these two quantities. To check whether a value is an unsigned infinity or
NAN, use is_uinf_or_nan. If it is,
then you can use is_nan for checking whether a value is NAN,
and if it it not, it must be an unsigned infinity. UNSIGNED_INF
belongs to the
class of "transfinite" numbers (see is_transfinite).
NAN
is an acronyme of Not_a_Number. TIOS generates NAN
when nothing can be deduced
about the magnitude of the result (for example, when dividing zero by zero, or when
substracting two infinities of the same sign). Also, TIOS generates NAN
when the
argument of a function is out of legal range, excluding values of the argument which
produces infinity results. For example, log will produce NAN
when the
argument is negative, but when the argument is zero, the result is
NEGATIVE_INF. See also UNSIGNED_INF.
NAN
also belongs to the class of "transfinite" numbers (see is_transfinite).
Use is_nan to check whether a value is NAN
. This is a common
method to check in run time whether the arguments of the called math functions was legal.