Table of Contents
complex.h
)math.h
)y
, magnitude of x
1 + x
Table of Contents
This chapter groups the complex mathematical functions. The
corresponding definitions and declarations are in complex.h
.
Functions and documentations are taken from NetBSD.
cabs — complex absolute-value
#include <complex.h>
double cabs( | double complex z) ; |
float cabsf( | float complex z) ; |
long double cabsl( | long double complex z) ; |
cacos — complex arc cosine
#include <complex.h>
double complex cacos( | double complex z) ; |
float complex cacosf( | float complex z) ; |
These functions compute the complex arc cosine of z
,
with branch cuts outside the interval [-1, +1] along the real axis.
cacosf
is identical to cacos
, except that it performs
its calculations on floats complex
.
cacosh — complex arc hyperbolic cosine
#include <complex.h>
double complex cacosh( | double complex z) ; |
float complex cacoshf( | float complex z) ; |
These functions compute the complex arc hyperbolic cosine of z
,
with a branch cut at values less than 1 along the real axis.
cacoshf
is identical to cacosh
, except that it performs
its calculations on floats complex
.
carg — argument (phase angle)
#include <complex.h>
double carg( | double complex z) ; |
float cargf( | float complex z) ; |
casin — complex arc sine
#include <complex.h>
double complex casin( | double complex z) ; |
float complex casinf( | float complex z) ; |
These functions compute the complex arc sine of z
,
with branch cuts outside the interval [-1, +1] along the real axis.
casinf
is identical to casin
, except that it performs
its calculations on floats complex
.
casinh — complex arc hyperbolic sine
#include <complex.h>
double complex casinh( | double complex z) ; |
float complex casinhf( | float complex z) ; |
These functions compute the complex arc hyperbolic sine of z
,
with branch cuts outside the interval [-i, +i] along the
imaginary axis.
casinhf
is identical to casinh
, except that it performs
its calculations on floats complex
.
catan — complex arc tangent
#include <complex.h>
double complex catan( | double complex z) ; |
float complex catanf( | float complex z) ; |
These functions compute the complex arc tangent of z
,
with branch cuts outside the interval [-i, +i] along the
imaginary axis.
catanf
is identical to catan
, except that it performs
its calculations on floats complex
.
catanh — complex arc hyperbolic tangent
#include <complex.h>
double complex catanh( | double complex z) ; |
float complex catanhf( | float complex z) ; |
These functions compute the complex arc hyperbolic tan of z
,
with branch cuts outside the interval [-1, +1] along the
real axis.
catanhf
is identical to catanh
, except that it performs
its calculations on floats complex
.
ccos — complex cosine
#include <complex.h>
double complex ccos( | double complex z) ; |
float complex ccosf( | float complex z) ; |
ccosh — complex hyperbolic cosine
#include <complex.h>
double complex ccosh( | double complex z) ; |
float complex ccoshf( | float complex z) ; |
cexp — complex base-e exponential
#include <complex.h>
double complex cexp( | double complex z) ; |
float complex cexpf( | float complex z) ; |
cimag — imaginary part
#include <complex.h>
double cimag( | double complex z) ; |
float cimagf( | float complex z) ; |
long double cimagl( | long double complex z) ; |
clog — complex base-e logarithm
#include <complex.h>
double complex clog( | double complex z) ; |
float complex clogf( | float complex z) ; |
These functions compute the complex natural (base-e
) logarithm
of z
, with a branch cut along the negative real axis.
clogf
is identical to clog
, except that it performs
its calculations on floats complex
.
conj — complex conjugate
#include <complex.h>
double complex conj( | double complex z) ; |
float complex conjf( | float complex z) ; |
cpow — complex power
#include <complex.h>
double complex cpow( | double complex x, |
double complex y) ; |
float complex cpowf( | float complex x, |
float complex y) ; |
cproj — Riemann sphere projection
#include <complex.h>
double complex cproj( | double complex z) ; |
float complex cprojf( | float complex z) ; |
These functions compute a projection of z
onto the Riemann
sphere: z
projects to z
except that all complex infinities
(even those with one infinite part and one NaN part) project
to positive infinity on the real axis. If z
has an infinite part,
then cproj
(z
) is equivalent to
INFINITY + I * copysign(0.0, cimag(z))
cprojf
is identical to cproj
, except that it performs
its calculations on floats complex
.
creal — real part
#include <complex.h>
double creal( | double complex z) ; |
float crealf( | float complex z) ; |
double long creall( | long double complex z) ; |
csin — complex sine
#include <complex.h>
double complex csin( | double complex z) ; |
float complex csinf( | float complex z) ; |
csinh — complex hyperbolic sine
#include <complex.h>
double complex csinh( | double complex z) ; |
float complex csinhf( | float complex z) ; |
csqrt — complex square root
#include <complex.h>
double complex csqrt( | double complex z) ; |
float complex csqrtf( | float complex z) ; |
These functions compute the complex square root of z
, with
a branch cut along the negative real axis.
csqrtf
is identical to csqrt
, except that it performs
its calculations on floats complex
.
ctan — complex tangent
#include <complex.h>
double complex ctan( | double complex z) ; |
float complex ctanf( | float complex z) ; |
ctanh — complex hyperbolic tangent
#include <complex.h>
double complex ctanh( | double complex z) ; |
float complex ctanhf( | float complex z) ; |
Table of Contents
y
, magnitude of x
1 + x
This chapter groups a wide variety of mathematical functions. The
corresponding definitions and declarations are in math.h
.
Two definitions from math.h
are of particular interest.
The representation of infinity as a double
is defined as
HUGE_VAL
; this number is returned on overflow by many functions.
The macro HUGE_VALF
is a corresponding value for float
.
The structure exception
is used when you write customized error
handlers for the mathematical functions. You can customize error
handling for most of these functions by defining your own version of
matherr
; see the section on matherr
for details.
Since the error handling code calls fputs
, the mathematical
subroutines require stubs or minimal implementations for the same list
of OS subroutines as fputs
: close
, fstat
,
isatty
, lseek
, read
, sbrk
, write
.
@xref{syscalls,,System Calls, libc.info, The Red Hat newlib C Library},
for a discussion and for sample minimal implementations of these support
subroutines.
Alternative declarations of the mathematical functions, which exploit
specific machine capabilities to operate faster---but generally have
less error checking and may reflect additional limitations on some
machines---are available when you include fastmath.h
instead of
math.h
.
acos — arc cosine
#include <math.h>
double acos( | double x) ; |
float acosf( | float x) ; |
acos
computes the inverse cosine (arc cosine) of the input value.
Arguments to acos
must be in the range −1 to 1.
acosf
is identical to acos
, except that it performs
its calculations on floats
.
acos
and acosf
return values in radians, in the range of 0 to pi.
If x
is not between −1 and 1, the returned value is NaN
(not a number) the global variable errno
is set to EDOM
, and a
DOMAIN error
message is sent as standard error output.
You can modify error handling for these functions using matherr
.
acosh — inverse hyperbolic cosine
#include <math.h>
double acosh( | double x) ; |
float acoshf( | float x) ; |
acosh
calculates the inverse hyperbolic cosine of x
.
acosh
is defined as
log(x
+ sqrt(x
*x
-1))
x
must be a number greater than or equal to 1.
acoshf
is identical, other than taking and returning floats.
asin — arc sine
#include <math.h>
double asin( | double x) ; |
float asinf( | float x) ; |
asinh — inverse hyperbolic sine
#include <math.h>
double asinh( | double x) ; |
float asinhf( | float x) ; |
atan — arc tangent
#include <math.h>
double atan( | double x) ; |
float atanf( | float x) ; |
atan2 — arc tangent of y/x
#include <math.h>
double atan2( | double y, |
double x) ; |
float atan2f( | float y, |
float x) ; |
atan2
computes the inverse tangent (arc tangent) of y
/x
.
atan2
produces the correct result even for angles near
pi/2 or -pi/2
(that is, when x
is near 0).
atan2f
is identical to atan2
, save that it takes and returns
float
.
atanh — inverse hyperbolic tangent
#include <math.h>
double atanh( | double x) ; |
float atanhf( | float x) ; |
atanh
calculates the inverse hyperbolic tangent of x
.
atanhf
is identical, other than taking and returning
float
values.
atanh
and atanhf
return the calculated value.
If
x
|
is greater than 1, the global errno
is set to EDOM
and
the result is a NaN. A DOMAIN error
is reported.
If
x
|
is 1, the global errno
is set to EDOM
; and the result is
infinity with the same sign as x
. A SING error
is reported.
You can modify the error handling for these routines using
matherr
.
jN — Bessel functions
#include <math.h>
double j0( | double x) ; |
float j0f( | float x) ; |
double j1( | double x) ; |
float j1f( | float x) ; |
double jn( | int n, |
double x) ; |
float jnf( | int n, |
float x) ; |
double y0( | double x) ; |
float y0f( | float x) ; |
double y1( | double x) ; |
float y1f( | float x) ; |
double yn( | int n, |
double x) ; |
float ynf( | int n, |
float x) ; |
The Bessel functions are a family of functions that solve the differential equation
2 2 2 x y'' + xy' + (x - p )y = 0
These functions have many applications in engineering and physics.
jn
calculates the Bessel function of the first kind of order
n
. j0
and j1
are special cases for order 0 and order
1 respectively.
Similarly, yn
calculates the Bessel function of the second kind of
order n
, and y0
and y1
are special cases for order 0 and
1.
jnf
, j0f
, j1f
, ynf
, y0f
, and y1f
perform the
same calculations, but on float
rather than double
values.
copysign — sign of y
, magnitude of x
#include <math.h>
double copysign( | double x, |
double y) ; |
float copysignf( | float x, |
float y) ; |
copysign
constructs a number with the magnitude (absolute value)
of its first argument, x
, and the sign of its second argument,
y
.
copysignf
does the same thing; the two functions differ only in
the type of their arguments and result.
cosh — hyperbolic cosine
#include <math.h>
double cosh( | double x) ; |
float coshf( | float x) ; |
cosh
computes the hyperbolic cosine of the argument x
.
cosh(
is defined as
x
)
(exp(x) + exp(-x))/2
Angles are specified in radians.
coshf
is identical, save that it takes and returns float
.
erf — error function
#include <math.h>
double erf( | double x) ; |
float erff( | float x) ; |
double erfc( | double x) ; |
float erfcf( | float x) ; |
erf
calculates an approximation to the ``error function'',
which estimates the probability that an observation will fall within
x
standard deviations of the mean (assuming a normal
distribution).
erfc
calculates the complementary probability; that is,
erfc(
is x
)1 - erf(
. x
)erfc
is computed directly,
so that you can use it to avoid the loss of precision that would
result from subtracting large probabilities (on large x
) from 1.
erff
and erfcf
differ from erf
and erfc
only in the
argument and result types.
exp — exponential
#include <math.h>
double exp( | double x) ; |
float expf( | float x) ; |
exp
and expf
calculate the exponential of x
, that is,
e raised to the power x
(where e
is the base of the natural system of logarithms, approximately 2.71828).
You can use the (non-ANSI) function matherr
to specify
error handling for these functions.
exp10 — exponential, base 10
#include <math.h>
double exp10( | double x) ; |
float exp10f( | float x) ; |
exp10
and exp10f
calculate 10 ^ x
, that is,
10 raised to the power x
.
You can use the (non-ANSI) function matherr
to specify
error handling for these functions.
exp2 — exponential, base 2
#include <math.h>
double exp2( | double x) ; |
float exp2f( | float x) ; |
exp2
and exp2f
calculate 2 ^ x
, that is,
2 raised to the power x
.
You can use the (non-ANSI) function matherr
to specify
error handling for these functions.
expm1 — exponential minus 1
#include <math.h>
double expm1( | double x) ; |
float expm1f( | float x) ; |
expm1
and expm1f
calculate the exponential of x
and subtract 1, that is,
e raised to the power x
minus 1 (where e
is the base of the natural system of logarithms, approximately
2.71828). The result is accurate even for small values of
x
, where using exp(
would lose many
significant digits.
x
)-1
fabs — absolute value (magnitude)
#include <math.h>
double fabs( | double x) ; |
float fabsf( | float x) ; |
fdim — positive difference
#include <math.h>
double fdim( | double x, |
double y) ; |
float fdimf( | float x, |
float y) ; |
floor — floor and ceiling
#include <math.h>
double floor( | double x) ; |
float floorf( | float x) ; |
double ceil( | double x) ; |
float ceilf( | float x) ; |
floor
and floorf
find
the nearest integer less than or equal to x
.
ceil
and ceilf
find
the nearest integer greater than or equal to x
.
fma — floating multiply add
#include <math.h>
double fma( | double x, |
double y, | |
double z) ; |
float fmaf( | float x, |
float y, | |
float z) ; |
The fma
functions compute (x
* y
) + z
, rounded as one ternary
operation: they compute the value (as if) to infinite precision and round once
to the result format, according to the rounding mode characterized by the value
of FLT_ROUNDS. That is, they are supposed to do this: see below.
This implementation does not provide the function that it should, purely
returning "(x
* y
) + z
;" with no attempt at all to provide the
simulated infinite precision intermediates which are required. DO NOT USE THEM.
If double has enough more precision than float, then fmaf
should provide
the expected numeric results, as it does use double for the calculation. But
since this is not the case for all platforms, this manual cannot determine
if it is so for your case.
fmax — maximum
#include <math.h>
double fmax( | double x, |
double y) ; |
float fmaxf( | float x, |
float y) ; |
fmin — minimum
#include <math.h>
double fmin( | double x, |
double y) ; |
float fminf( | float x, |
float y) ; |
fmod — floating-point remainder (modulo)
#include <math.h>
double fmod( | double x, |
double y) ; |
float fmodf( | float x, |
float y) ; |
frexp — split floating-point number
#include <math.h>
double frexp( | double val, |
int *exp) ; |
float frexpf( | float val, |
int *exp) ; |
All nonzero, normal numbers can be described as m
* 2**p
.
frexp
represents the double val
as a mantissa m
and a power of two p
. The resulting mantissa will always
be greater than or equal to 0.5
, and less than 1.0
(as
long as val
is nonzero). The power of two will be stored
in *
exp
.
m
and p
are calculated so that
val
is m
times 2
to the power p
.
frexpf
is identical, other than taking and returning
floats rather than doubles.
gamma — logarithmic and plain gamma functions
#include <math.h>
double gamma( | double x) ; |
float gammaf( | float x) ; |
double lgamma( | double x) ; |
float lgammaf( | float x) ; |
double gamma_r( | double x, |
int *signgamp) ; |
float gammaf_r( | float x, |
int *signgamp) ; |
double lgamma_r( | double x, |
int *signgamp) ; |
float lgammaf_r( | float x, |
int *signgamp) ; |
double tgamma( | double x) ; |
float tgammaf( | float x) ; |
gamma
calculates
the natural logarithm of the gamma function of x
. The gamma function
(exp(gamma(
) is a generalization of factorial, and retains
the property that
x
))exp(gamma(N))
is equivalent to N*exp(gamma(N-1))
.
Accordingly, the results of the gamma function itself grow very
quickly. gamma
is defined as
the natural log of the gamma function, rather than the gamma function
itself,
to extend the useful range of results representable.
The sign of the result is returned in the global variable signgam
,
which is declared in math.h.
gammaf
performs the same calculation as gamma
, but uses and
returns float
values.
lgamma
and lgammaf
are alternate names for gamma
and
gammaf
. The use of lgamma
instead of gamma
is a reminder
that these functions compute the log of the gamma function, rather
than the gamma function itself.
The functions gamma_r
, gammaf_r
, lgamma_r
, and
lgammaf_r
are just like gamma
, gammaf
, lgamma
, and
lgammaf
, respectively, but take an additional argument. This
additional argument is a pointer to an integer. This additional
argument is used to return the sign of the result, and the global
variable signgam
is not used. These functions may be used for
reentrant calls (but they will still set the global variable errno
if an error occurs).
tgamma
and tgammaf
are the "true gamma" functions, returning
the gamma function of x
--without a logarithm.
(They are apparently so named because of the prior existence of the old,
poorly-named gamma
functions which returned the log of gamma up
through BSD 4.2.)
Normally, the computed result is returned.
When x
is a nonpositive integer, gamma
returns HUGE_VAL
and errno
is set to EDOM
. If the result overflows, gamma
returns HUGE_VAL
and errno
is set to ERANGE
.
You can modify this error treatment using matherr
.
Neither gamma
nor gammaf
is ANSI C. It is better not to use either
of these; use lgamma
or tgamma
instead.
lgamma
, lgammaf
, tgamma
, and tgammaf
are nominally C standard
in terms of the base return values, although the matherr
error-handling
is not standard, nor is the signgam
global for lgamma
.
hypot — distance from origin
#include <math.h>
double hypot( | double x, |
double y) ; |
float hypotf( | float x, |
float y) ; |
hypot
calculates the Euclidean distance
sqrt(
between the origin (0,0) and a point represented by the
Cartesian coordinates (x
*x
+ y
*y
)x
,y
). hypotf
differs only
in the type of its arguments and result.
ilogb — get exponent of floating-point number
#include <math.h>
int ilogb( | double val) ; |
int ilogbf( | float val) ; |
All nonzero, normal numbers can be described as m
*
2**p
. ilogb
and ilogbf
examine the argument
val
, and return p
. The functions frexp
and
frexpf
are similar to ilogb
and ilogbf
, but also
return m
.
ilogb
and ilogbf
return the power of two used to form the
floating-point argument.
If val
is 0
, they return FP_ILOGB0
.
If val
is infinite, they return INT_MAX
.
If val
is NaN, they return FP_ILOGBNAN
.
(FP_ILOGB0
and FP_ILOGBNAN
are defined in math.h, but in turn are
defined as INT_MIN or INT_MAX from limits.h. The value of FP_ILOGB0 may be
either INT_MIN or -INT_MAX. The value of FP_ILOGBNAN may be either INT_MAX or
INT_MIN.)
infinity — representation of infinity
#include <math.h>
double infinity( | void) ; |
float infinityf( | void) ; |
infinity
and infinityf
return the special number IEEE
infinity in double- and single-precision arithmetic
respectively.
infinity
and infinityf
are neither standard C nor POSIX. C and
POSIX require macros HUGE_VAL and HUGE_VALF to be defined in math.h, which
Newlib defines to be infinities corresponding to these archaic infinity()
and infinityf() functions in floating-point implementations which do have
infinities.
isgreater — comparison macros
#include <math.h>
int isgreater( | real-floating x, |
real-floating y) ; |
int isgreaterequal( | real-floating x, |
real-floating y) ; |
int isless( | real-floating x, |
real-floating y) ; |
int islessequal( | real-floating x, |
real-floating y) ; |
int islessgreater( | real-floating x, |
real-floating y) ; |
int isunordered( | real-floating x, |
real-floating y) ; |
isgreater
, isgreaterequal
, isless
, islessequal
,
islessgreater
, and isunordered
are macros defined for use in
comparing floating-point numbers without raising any floating-point
exceptions.
The relational operators (i.e. <, >, <=, and >=) support the usual mathematical relationships between numeric values. For any ordered pair of numeric values exactly one of the relationships--less, greater, and equal--is true. Relational operators may raise the "invalid" floating-point exception when argument values are NaNs. For a NaN and a numeric value, or for two NaNs, just the unordered relationship is true (i.e., if one or both of the arguments a NaN, the relationship is called unordered). The specified macros are quiet (non floating-point exception raising) versions of the relational operators, and other comparison macros that facilitate writing efficient code that accounts for NaNs without suffering the "invalid" floating-point exception. In the synopses shown, "real-floating" indicates that the argument is an expression of real floating type.
Please note that saying that the macros do not raise floating-point exceptions, it is referring to the function that they are performing. It is certainly possible to give them an expression which causes an exception. For example:
NaN < 1.0
| causes an "invalid" exception, |
isless(NaN, 1.0)
| does not, and |
isless(NaN*0., 1.0)
| causes an exception due to the "NaN*0.", but not from the resultant reduced comparison of isless(NaN, 1.0). |
No floating-point exceptions are raised for any of the macros.
The isgreater
macro returns the value of (x) > (y).
The isgreaterequal
macro returns the value of (x) >= (y).
The isless
macro returns the value of (x) < (y).
The islessequal
macro returns the value of (x) <= (y).
The islessgreater
macro returns the value of (x) < (y) || (x) > (y).
The isunordered
macro returns 1 if either of its arguments is NaN and 0 otherwise.
fpclassify — floating-point classification macros, test for exceptional numbers
[C99 standard macros:]
#include <math.h>
int fpclassify( | real-floating x) ; |
int isfinite( | real-floating x) ; |
int isinf( | real-floating x) ; |
int isnan( | real-floating x) ; |
int isnormal( | real-floating x) ; |
[Archaic SUSv2 functions:]
#include <ieeefp.h>
int isnan( | double arg) ; |
int isinf( | double arg) ; |
int finite( | double arg) ; |
int isnanf( | float arg) ; |
int isinff( | float arg) ; |
int finitef( | float arg) ; |
fpclassify
, isfinite
, isinf
, isnan
, and isnormal
are macros
defined for use in classifying floating-point numbers. This is a help because
of special "values" like NaN and infinities. In the synopses shown,
"real-floating" indicates that the argument is an expression of real floating
type. These function-like macros are C99 and POSIX-compliant, and should be
used instead of the now-archaic SUSv2 functions.
The fpclassify
macro classifies its argument value as NaN, infinite, normal,
subnormal, zero, or into another implementation-defined category. First, an
argument represented in a format wider than its semantic type is converted to
its semantic type. Then classification is based on the type of the argument.
The fpclassify
macro returns the value of the number classification macro
appropriate to the value of its argument:
FP_INFINITE
|
|
FP_NAN
|
|
FP_NORMAL
|
|
FP_SUBNORMAL
|
|
FP_ZERO
|
|
The "is
" set of macros provide a useful set of shorthand ways for
classifying floating-point numbers, providing the following equivalent
relations:
|
returns non-zero if |
|
returns non-zero if |
|
returns non-zero if |
|
returns non-zero if |
The archaic SUSv2 functions provide information on the floating-point argument supplied.
There are five major number formats ("exponent" referring to the biased exponent in the binary-encoded number):
zero
| A number which contains all zero bits, excluding the sign bit. |
subnormal
| A number with a zero exponent but a nonzero fraction. |
normal
| A number with an exponent and a fraction. |
infinity
| A number with an all 1's exponent and a zero fraction. |
NAN
| A number with an all 1's exponent and a nonzero fraction. |
isnan
returns 1 if the argument is a nan. isinf
returns 1 if the argument is infinity. finite
returns 1 if the
argument is zero, subnormal or normal.
The isnanf
, isinff
and finitef
functions perform the same
operations as their isnan
, isinf
and finite
counterparts, but on single-precision floating-point numbers.
It should be noted that the C99 standard dictates that isnan
and isinf
are macros that operate on multiple types of
floating-point. The SUSv2 standard declares isnan
as
a function taking double. Newlib has decided to declare
them both as macros in math.h and as functions in ieeefp.h to
maintain backward compatibility.
The fpclassify macro returns the value corresponding to the appropriate FP_ macro.
The isfinite macro returns nonzero if x
is finite, else 0.
The isinf macro returns nonzero if x
is infinite, else 0.
The isnan macro returns nonzero if x
is an NaN, else 0.
The isnormal macro returns nonzero if x
has a normal value, else 0.
ldexp — load exponent
#include <math.h>
double ldexp( | double val, |
int exp) ; |
float ldexpf( | float val, |
int exp) ; |
ldexp
calculates the value
val
times 2 to the power exp
.
ldexpf
is identical, save that it takes and returns float
rather than double
values.
log — natural logarithms
#include <math.h>
double log( | double x) ; |
float logf( | float x) ; |
Return the natural logarithm of x
, that is, its logarithm base e
(where e is the base of the natural system of logarithms, 2.71828…).
log
and logf
are identical save for the return and argument types.
You can use the (non-ANSI) function matherr
to specify error
handling for these functions.
log10 — base 10 logarithms
#include <math.h>
double log10( | double x) ; |
float log10f( | float x) ; |
log10
returns the base 10 logarithm of x
.
It is implemented as log(
.
x
) / log(10)
log10f
is identical, save that it takes and returns float
values.
log1p — log of 1 +
x
#include <math.h>
double log1p( | double x) ; |
float log1pf( | float x) ; |
log1p
calculates
the natural logarithm of 1+
. You can use x
log1p
rather
than `log(1+
' for greater precision when x
)x
is very
small.
log1pf
calculates the same thing, but accepts and returns
float
values rather than double
.
log2 — base 2 logarithm
#include <math.h>
double log2( | double x) ; |
float log2f( | float x) ; |
The log2
functions compute the base-2 logarithm of x
. A domain error
occurs if the argument is less than zero. A range error occurs if the
argument is zero.
The Newlib implementations are not full, intrinisic calculations, but
rather are derivatives based on log
. (Accuracy might be slightly off from
a direct calculation.) In addition to functions, they are also implemented as
macros defined in math.h:
#define log2(x) (log (x) / _M_LN2) #define log2f(x) (logf (x) / (float) _M_LN2)
To use the functions instead, just undefine the macros first.
You can use the (non-ANSI) function matherr
to specify error
handling for these functions, indirectly through the respective log
function.
logb — get exponent of floating-point number
#include <math.h>
double logb( | double x) ; |
float logbf( | float x) ; |
The logb
functions extract the exponent of x
, as a signed integer value
in floating-point format. If x
is subnormal it is treated as though it were
normalized; thus, for positive finite x
,
1 <= (x
* FLT_RADIX to the power (-logb(x
))) < FLT_RADIX.
A domain error may occur if the argument is zero.
In this floating-point implementation, FLT_RADIX is 2. Which also means
that for finite x
, logb
(x
) = floor
(log2
(fabs
(x
))).
All nonzero, normal numbers can be described as
m
* 2**p
, where 1.0 <= m
< 2.0.
The logb
functions examine the argument x
, and return p
.
The frexp
functions are similar to the logb
functions, but
returning m
adjusted to the interval [.5, 1) or 0, and p
+1.
lrint — round to integer
#include <math.h>
long int lrint( | double x) ; |
long int lrintf( | float x) ; |
long long int llrint( | double x) ; |
long long int llrintf( | float x) ; |
The lrint
and llrint
functions round their argument to the nearest
integer value, using the current rounding direction. If the rounded value is
outside the range of the return type, the numeric result is unspecified. A
range error may occur if the magnitude of x
is too large.
The "inexact" floating-point exception is raised in implementations that
support it when the result differs in value from the argument (i.e., when
a fraction actually has been truncated).
lround — round to integer, to nearest
#include <math.h>
long int lround( | double x) ; |
long int lroundf( | float x) ; |
long long int llround( | double x) ; |
long long int llroundf( | float x) ; |
The lround
and llround
functions round their argument to the
nearest integer value, rounding halfway cases away from zero, regardless
of the current rounding direction. If the rounded value is outside the
range of the return type, the numeric result is unspecified (depending
upon the floating-point implementation, not the library). A range
error may occur if the magnitude of x is too large.
matherr — modifiable math error handler
#include <math.h>
int matherr( | struct exception *e) ; |
matherr
is called whenever a math library function generates an error.
You can replace matherr
by your own subroutine to customize
error treatment. The customized matherr
must return 0 if
it fails to resolve the error, and non-zero if the error is resolved.
When matherr
returns a nonzero value, no error message is printed
and the value of errno
is not modified. You can accomplish either
or both of these things in your own matherr
using the information
passed in the structure *
.
e
This is the exception
structure (defined in `math.h
'):
struct exception { int type; char *name; double arg1, arg2, retval; int err; };
The members of the exception structure have the following meanings:
type
|
The type of mathematical error that occured; macros encoding error
types are also defined in ` |
name
| a pointer to a null-terminated string holding the name of the math library function where the error occurred. |
arg1, arg2
| The arguments which caused the error. |
retval
| The error return value (what the calling function will return). |
err
|
If set to be non-zero, this is the new value assigned to |
The error types defined in `math.h
' represent possible mathematical
errors as follows:
DOMAIN
|
An argument was not in the domain of the function; e.g. |
SING
|
The requested calculation would result in a singularity; e.g. |
OVERFLOW
|
A calculation would produce a result too large to represent; e.g.
|
UNDERFLOW
|
A calculation would produce a result too small to represent; e.g.
|
TLOSS
|
Total loss of precision. The result would have no significant digits;
e.g. |
PLOSS
|
Partial loss of precision. |
The library definition for matherr
returns 0
in all cases.
You can change the calling function's result from a customized matherr
by modifying e->retval
, which propagates backs to the caller.
If matherr
returns 0
(indicating that it was not able to resolve
the error) the caller sets errno
to an appropriate value, and prints
an error message.
modf — split fractional and integer parts
#include <math.h>
double modf( | double val, |
double *ipart) ; |
float modff( | float val, |
float *ipart) ; |
modf
splits the double val
apart into an integer part
and a fractional part, returning the fractional part and
storing the integer part in *
. No rounding
whatsoever is done; the sum of the integer and fractional
parts is guaranteed to be exactly equal to ipart
val
. That
is, if realpart
= modf(val
, &intpart
); then
`
' is the same as realpart
+intpart
val
.
modff
is identical, save that it takes and returns
float
rather than double
values.
nan — representation of ``Not a Number''
#include <math.h>
double nan( | const char *unused) ; |
float nanf( | const char *unused) ; |
nearbyint — round to integer
#include <math.h>
double nearbyint( | double x) ; |
float nearbyintf( | float x) ; |
The nearbyint
functions round their argument to an integer value in
floating-point format, using the current rounding direction and
(supposedly) without raising the "inexact" floating-point exception.
See the rint
functions for the same function with the "inexact"
floating-point exception being raised when appropriate.
Newlib does not support the floating-point exception model, so that
the floating-point exception control is not present and thereby what may
be seen will be compiler and hardware dependent in this regard.
The Newlib nearbyint
functions are identical to the rint
functions with respect to the floating-point exception behavior, and
will cause the "inexact" exception to be raised for most targets.
nextafter — get next number
#include <math.h>
double nextafter( | double val, |
double dir) ; |
float nextafterf( | float val, |
float dir) ; |
pow — x to the power y
#include <math.h>
double pow( | double x, |
double y) ; |
float powf( | float x, |
float y) ; |
On success, pow
and powf
return the value calculated.
When the argument values would produce overflow, pow
returns HUGE_VAL
and set errno
to ERANGE
. If the
argument x
passed to pow
or powf
is a negative
noninteger, and y
is also not an integer, then errno
is set to EDOM
. If x
and y
are both 0, then
pow
and powf
return 1
.
You can modify error handling for these functions using matherr
.
pow10 — base 10 power functions
#include <math.h>
double pow10( | double x) ; |
float pow10f( | float x) ; |
pow10
and pow10f
calculate 10 ^ x
, that is,
10 raised to the power x
.
You can use the (non-ANSI) function matherr
to specify
error handling for these functions.
remainder — round and remainder
#include <math.h>
double remainder( | double x, |
double y) ; |
float remainderf( | float x, |
float y) ; |
remquo — remainder and part of quotient
#include <math.h>
double remquo( | double x, |
double y, | |
int *quo) ; |
float remquof( | float x, |
float y, | |
int *quo) ; |
The remquo
functions compute the same remainder as the remainder
functions; this value is in the range -y
/2 ... +y
/2. In the object
pointed to by quo
they store a value whose sign is the sign of x
/y
and whose magnitude is congruent modulo 2**n to the magnitude of the integral
quotient of x
/y
. (That is, quo
is given the n lsbs of the
quotient, not counting the sign.) This implementation uses n=31 if int is 32
bits or more, otherwise, n is 1 less than the width of int.
For example:
remquo(-29.0, 3.0, &quo
)
returns -1.0 and sets quo
=10, and
remquo(-98307.0, 3.0, &quo
)
returns -0.0 and sets quo
=-32769, although for 16-bit int, quo
=-1. In
the latter case, the actual quotient of -(32769=0x8001) is reduced to -1
because of the 15-bit limitation for the quotient.
When either argument is NaN, NaN is returned. If y
is 0 or x
is
infinite (and neither is NaN), a domain error occurs (i.e. the "invalid"
floating point exception is raised or errno is set to EDOM), and NaN is
returned.
Otherwise, the remquo
functions return x
REM y
.
rint — round to integer
#include <math.h>
double rint( | double x) ; |
float rintf( | float x) ; |
The rint
functions round their argument to an integer value in
floating-point format, using the current rounding direction. They
raise the "inexact" floating-point exception if the result differs
in value from the argument. See the nearbyint
functions for the
same function with the "inexact" floating-point exception never being
raised. Newlib does not directly support floating-point exceptions.
The rint
functions are written so that the "inexact" exception is
raised in hardware implementations that support it, even though Newlib
does not provide access.
round — round to integer, to nearest
#include <math.h>
double round( | double x) ; |
float roundf( | float x) ; |
The round
functions round their argument to the nearest integer
value in floating-point format, rounding halfway cases away from zero,
regardless of the current rounding direction. (While the "inexact"
floating-point exception behavior is unspecified by the C standard, the
round
functions are written so that "inexact" is not raised if the
result does not equal the argument, which behavior is as recommended by
IEEE 754 for its related functions.)
scalbn — scale by power of FLT_RADIX (=2)
#include <math.h>
double scalbn( | double x, |
int n) ; |
float scalbnf( | float x, |
int n) ; |
double scalbln( | double x, |
long int n) ; |
float scalblnf( | float x, |
long int n) ; |
The scalbn
and scalbln
functions compute
x
times FLT_RADIX to the power n
.
efficiently. The result is computed by manipulating the exponent, rather than
by actually performing an exponentiation or multiplication. In this
floating-point implementation FLT_RADIX=2, which makes the scalbn
functions equivalent to the ldexp
functions.
signbit — Does floating-point number have negative sign?
#include <math.h>
int signbit( | real-floating x) ; |
The signbit
macro determines whether the sign of its argument value is
negative. The macro reports the sign of all values, including infinities,
zeros, and NaNs. If zero is unsigned, it is treated as positive. As shown in
the synopsis, the argument is "real-floating," meaning that any of the real
floating-point types (float, double, etc.) may be given to it.
Note that because of the possibilities of signed 0 and NaNs, the expression
"x
< 0.0" does not give the same result as signbit
in all cases.
sin — sine or cosine
#include <math.h>
double sin( | double x) ; |
float sinf( | float x) ; |
double cos( | double x) ; |
float cosf( | float x) ; |
sinh — hyperbolic sine
#include <math.h>
double sinh( | double x) ; |
float sinhf( | float x) ; |
sinh
computes the hyperbolic sine of the argument x
.
Angles are specified in radians. sinh
(x
) is defined as
(exp(x
) - exp(-x
))/2
sinhf
is identical, save that it takes and returns float
values.
sqrt — positive square root
#include <math.h>
double sqrt( | double x) ; |
float sqrtf( | float x) ; |
sqrt
computes the positive square root of the argument.
You can modify error handling for this function with
matherr
.
tan — tangent
#include <math.h>
double tan( | double x) ; |
float tanf( | float x) ; |
tanh — hyperbolic tangent
#include <math.h>
double tanh( | double x) ; |
float tanhf( | float x) ; |
trunc — round to integer, towards zero
#include <math.h>
double trunc( | double x) ; |
float truncf( | float x) ; |
The trunc
functions round their argument to the integer value, in
floating format, nearest to but no larger in magnitude than the
argument, regardless of the current rounding direction. (While the
"inexact" floating-point exception behavior is unspecified by the C
standard, the trunc
functions are written so that "inexact" is not
raised if the result does not equal the argument, which behavior is as
recommended by IEEE 754 for its related functions.)