|
Document revision date: 19 July 1999
|
![[Compaq]](../../images/compaq.gif) |
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
|
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
|
DIGITAL Portable Mathematics Library
atanh - Hyperbolic Arc Tangent of Angle
Interface
F_TYPE atanh (F_TYPE x)
Description
atanh() returns the hyperbolic arc tangent of x for x in the interval
(-1,1). atanh() is the inverse function of tanh(), where atanh(tanh
(x)) = x.
atanh(x) is computed as 1/2 ln((1+x)/(1-x)).
Exceptions
| Exceptional Argument |
Routine Behavior |
|
|x| > or = 1
|
Invalid argument
|
bessel - Bessel Functions
Interface
F_TYPE j0 (F_TYPE x)
F_TYPE j1 (F_TYPE x)
F_TYPE jn (int n, F_TYPE x)
F_TYPE y0 (F_TYPE x)
F_TYPE y1 (F_TYPE x)
F_TYPE yn (int n, F_TYPE x)
Description
j0() and j1() return the value of the Bessel function of the first kind
of orders 0 and 1 respectively.
jn() returns the value of the Bessel function of the first kind of
order n.
y0() and y1() return the value Bessel function of the second kind of
orders 0 and 1 respectively.
yn() returns the value of the Bessel function of the second kind of
order n.
The value of x must be positive for the y family of Bessel functions.
The value of n specifies some integer value.
Exceptions
| Exceptional Argument |
Routine Behavior |
|
(y0(), y1(), yn()) x < 0
|
Invalid argument
|
|
(y0(), y1(), yn()) x = 0
|
Overflow
|
The j1() and jn() functions can result in an underflow as x gets
small. The largest value of x for which this occurs is a function of n.
The y1() and yn() functions can result in an overflow as x gets
small. The largest value of x for which this occurs is a function of n.
cabs - Complex Absolute Value
Interface
F_TYPE cabs (F_TYPE x, F_TYPE y)
Description
cabs(x,y) is defined as the square root of (x**2 + y**2) and returns
the same value as hypot(x,y).
Exceptions
| Exceptional Argument |
Routine Behavior |
|
sqrt(x**2 + y**2) > max_float
|
Overflow
|
See Also
Appendix A, Critical Floating-Point Values
cbrt - Cube Root
Interface
F_TYPE cbrt (F_TYPE x)
Description
cbrt() returns the rounded cube root of x.
Exceptions
None.
ccos - Cosine of Angle of a Complex Number
Interface
F_COMPLEX ccos (F_TYPE x, F_TYPE y)
Description
ccos() returns the cosine of a complex number, x + iy.
ccos(x,y) is defined as cos (x + iy) = (cos x cosh
y-isin x sinh y).
Exceptions
| Exceptional Argument |
Routine Behavior |
|
|y| = infinity
|
Invalid argument
|
|
(sin x sinh y) > max_float
|
Overflow
|
|
(cos x cosh y) > max_float
|
Overflow
|
See Also
Appendix A, Critical Floating-Point Values
cdiv - Complex Division
Interface
F_COMPLEX cdiv (F_TYPE a, F_TYPE b, F_TYPE c, F_TYPE d)
Description
cdiv() returns the quotient of two complex numbers: (a +
ib)/(c + id).
Exceptions
| Exceptional Argument |
Routine Behavior |
|
c=d=0
|
Invalid argument
|
|
a=b=c=d=0
|
Invalid argument
|
ceil - Ceiling
Interface
F_TYPE ceil (F_TYPE x)
Description
ceil() returns the smallest floating-point integer value greater than
or equal to x.
Exceptions
None.
cexp - Complex Exponential
Interface
F_COMPLEX cexp (F_TYPE x, F_TYPE y)
Description
cexp() returns the exponential of a complex number.
cexp(x,y) is defined as e**(x + iy) = e**x cos y +
ie**x sin y.
Exceptions
| Exceptional Argument |
Routine Behavior |
|
|y| = infinity
|
Invalid argument
|
|
|e**x cos y| > max_float
|
Overflow
|
|
|e**x sin y| > max_float
|
Overflow
|
|
|e**x cos y| < min_float
|
Underflow
|
|
|e**x sin y| < min_float
|
Underflow
|
See Also
Appendix A, Critical Floating-Point Values
clog - Complex Natural Logarithm
Interface
F_COMPLEX clog (F_TYPE x, F_TYPE y)
Description
clog() returns the natural logarithm of a complex number.
clog(x,y) is defined as ln(x + iy) = 1/2 ln(x**2 + y**2) +
iatan2 (y,x).
Exceptions
| Exceptional Argument |
Routine Behavior |
|
y=x=0
|
Invalid argument
|
|
|y|=|x|=infinity
|
Invalid argument
|
cmul - Complex Multiplication
Interface
F_COMPLEX cmul (F_TYPE a, F_TYPE b, F_TYPE c, F_TYPE d)
Description
cmul() returns the product of two complex numbers.
cmul(a,b,c,d) is defined as (a + ib) * (c + id).
Exceptions
None.
copysign - Copy Sign
Interface
F_TYPE copysign (F_TYPE x, F_TYPE y)
Description
copysign() returns x with the same sign as y. IEEE Std 754 requires
copysign(x,NaN) = +x or -x.
Exceptions
None.
cos - Cosine of Angle
Interface
F_TYPE cos (F_TYPE x)
F_TYPE cosd (F_TYPE x)
Description
cos() computes the cosine of x, measured in radians.
cosd() computes the cosine of x, measured in degrees.
Exceptions
| Exceptional Argument |
Routine Behavior |
|
|x| = infinity
|
Invalid argument
|
cosh - Hyperbolic Cosine of Angle
Interface
F_TYPE cosh (F_TYPE x)
Description
cosh() computes the hyperbolic cosine of x.
cosh(x) is defined as (e**x + e**(-x))/2.
Exceptions
| Exceptional Argument |
Routine Behavior |
|
|x| > ln(2 * max_float)
|
Overflow
|
See Also
Appendix A, Critical Floating-Point Values
cot - Cotangent of Angle
Interface
F_TYPE cot (F_TYPE x)
F_TYPE cotd (F_TYPE x)
Description
cot() computes the cotangent of x, measured in radians.
cotd() computes the cotangent of x, measured in degrees.
Exceptions
| Exceptional Argument |
Routine Behavior |
|
(cot) x=0
|
Overflow
|
|
(cotd) |x| = multiples of 180 degrees
|
Overflow
|
cpow - Complex Power
Interface
F_COMPLEX cpow (F_TYPE a, F_TYPE b, F_TYPE c, F_TYPE d)
Description
cpow() raises a complex base (a + ib) to a complex exponent (c
+ id).
cpow(a,b,c,d) is defined as e**((c + id) ln(a + ib)).
Exceptions
| Exceptional Argument |
Routine Behavior |
|
sqrt (a**2 + b**2) > max_float
|
Overflow
|
|
c/2 * ln(a**2 + b**2) > max_float
|
Overflow
|
|
c/2 * ln(a**2 + b**2) - (d * atan2(b,c)) > max_float
|
Overflow
|
See Also
Appendix A, Critical Floating-Point Values
csin - Sine of Angle of a Complex Number
Interface
F_COMPLEX csin (F_TYPE x, F_TYPE y)
Description
csin() computes the sine of a complex number, x + iy.
csin(x,y) is defined as sin (x + iy) = (sin x cosh iy
+ icos x sinh iy).
Exceptions
| Exceptional Argument |
Routine Behavior |
|
|y| = infinity
|
Invalid argument
|
|
(sinh x sin y) > max_float
|
Overflow
|
|
(cosh x cos y) > max_float
|
Overflow
|
See Also
Appendix A, Critical Floating-Point Values
csqrt - Complex Square Root
Interface
F_COMPLEX csqrt (F_TYPE x, F_TYPE y)
Description
csqrt() computes the square root of a complex number, x + iy.
The real part of csqrt is greater than or equal to zero.
csqrt(x,y) is defined as the square root of (x + iy).
Exceptions
None.
cvt_ftof - Convert Between Supported Floating-Point Data Types
Interface
int cvt_ftof void *x, int x_type, void *y, int y_type, options
Description
Note
This routine does not apply to OpenVMS Alpha. OpenVMS Alpha users
should use the CVT$FTOF routine documented in the OpenVMS RTL
Library (LIB$) Manual.
|
cvt_ftof() converts a floating-point value from one data type to
another. x points to the input value to be converted, and y points to
the converted result. The conversion is subject to the options
specified in the options (bit field) argument.
x_type and y_type identify the data type of x and y as follows:
| Values for x_type and y_type |
Floating-Point Data Type |
|
CVT_VAX_F
|
VAX F Floating ( 4 bytes)
|
|
CVT_VAX_D
|
VAX D Floating ( 8 bytes)
|
|
CVT_VAX_G
|
VAX G Floating ( 8 bytes)
|
|
CVT_VAX_H
|
VAX H Floating (16 bytes)
|
|
CVT_IEEE_S
|
IEEE Little Endian S Floating ( 4 bytes)
|
|
CVT_IEEE_T
|
IEEE Little Endian T Floating ( 8 bytes)
|
|
CVT_IEEE_X
|
IEEE Little Endian X Floating (16 bytes)
|
|
CVT_BIG_ENDIAN_IEEE_S
|
IEEE Big Endian S Floating ( 4 bytes)
|
|
CVT_BIG_ENDIAN_IEEE_T
|
IEEE Big Endian T Floating ( 8 bytes)
|
|
CVT_BIG_ENDIAN_IEEE_X
|
IEEE Big Endian X Floating (16 bytes)
|
|
CVT_IBM_SHORT
|
IBM_Short_Floating ( 4 bytes)
|
|
CVT_IBM_LONG
|
IBM_Long_Floating ( 8 bytes)
|
|
CVT_CRAY_SINGLE
|
CRAY_Floating ( 8 bytes)
|
Provide a zero (0) value to the options argument to select default
behavior or choose one or more options (status condition option,
rounding options, "FORCE" options, CRAY and IBM options) from the
tables below as the options argument. Specify only the options that
apply to your conversion. A conflicting or incompatable options
argument will be reported as an error (CVT_INVALID_OPTION).
| Applicable Conversion |
Status Condition Option |
Description |
|
|
All
|
CVT_REPORT_ALL
|
Report all applicable status conditions as the default. The reporting
of recoverable status conditions is disabled by default when this
option is not used.
|
|
| Applicable Conversion |
Rounding Options |
Description |
|
|
All
|
CVT_ROUND_TO_NEAREST
|
The default rounding option for conversions to IEEE data types. This
IEEE Std. 754 rounding mode results in the representable output value
nearest to the infinitely precise result. If the two nearest
representable values are equally near, the one with its least
significant bit zero is the result.
|
|
|
All
|
CVT_BIASED_ROUNDING
|
The default rounding option for conversions to non-IEEE data types.
Performs "traditional" style rounding. This mode results in the
representable output value nearest to the infinitely precise result. If
the two nearest representable values are equally near, the result is
the value with the largest magnitude.
|
|
|
All
|
CVT_ROUND_TO_ZERO
|
Round the output value toward zero (truncate).
|
|
|
All
|
CVT_ROUND_TO_POS
|
Round the output value toward positive infinity.
|
|
|
All
|
CVT_ROUND_TO_NEG
|
Round the output value toward negative infinity.
|
|
| Applicable Conversion |
"FORCE" Options |
Description |
|
|
All
|
CVT_FORCE_ALL_SPECIAL_VALUES
|
Apply all applicable "FORCE" options for the current conversion.
|
|
|
IEEE
|
CVT_FORCE_DENORM_TO_ZERO
1
|
Force a denormalized IEEE output value to zero.
|
|
|
IEEE
|
CVT_FORCE_INF_TO_MAX_FLOAT
1
|
Force a positive IEEE infinite output value to +max_float and force a
negative IEEE infinite output value to -max_float.
|
|
|
IEEE or VAX
|
CVT_FORCE_INVALID_TO_ZERO
2
|
Force an invalid IEEE NaN (not a number) output value or a VAX ROP
(reserved operand) output value to zero.
|
|
1This option is valid only for conversions to IEEE output
values.
2This option is valid only for conversions to IEEE or VAX
output values.
| Applicable Conversion |
Options for CRAY Format Conversion |
Description |
|
|
CRAY
|
CVT_ALLOW_OVRFLW_RANGE_VALUES
|
Allow an input/output exponent value > 60000 (8).
|
|
|
CRAY
|
CVT_ALLOW_UDRFLW_RANGE_VALUES
|
Allow an input/output exponent value < 20000 (8).
|
|
| Applicable Conversion |
Option for IBM Format Conversion |
Description |
|
|
IBM
|
CVT_ALLOW_UNNORMALIZED_VALUES
|
Allow unnormalized input arguments. Allow an unnormalized output value
for a small value which would normalize to zero.
|
|
Returns
The return value is a bit field containing the
condition codes raised by the function. cvt_ftof() returns CVT_NORMAL;
otherwise, it sets one or more of the following recoverable and
unrecoverable conditions. Use the following condition names to
determine which conditions are set:
| Condition Name |
Condition (Always reported by default) |
|
|
CVT_INVALID_INPUT_TYPE
|
Invalid input type code.
|
|
CVT_INVALID_OUTPUT_TYPE
|
Invalid output type code.
|
|
CVT_INVALID_OPTION
|
Invalid option argument.
|
| Condition Name |
Condition (Only reported if the CVT_REPORT_ALL option is selected) |
|
|
CVT_RESULT_INFINITE
|
Conversion produced an infinite result.
1
|
|
CVT_RESULT_DENORMALIZED
|
Conversion produced a denormalized result.
1
|
|
CVT_RESULT_OVERFLOW_RANGE
|
Conversion yielded an exponent > 60000 (8).
2
|
|
CVT_RESULT_UNDERFLOW_RANGE
|
Conversion yielded an exponent < 20000 (8).
2
|
|
CVT_RESULT_UNNORMALIZED
|
Conversion produced an unnormalized result.
3
|
|
CVT_RESULT_INVALID
|
Conversion result is either ROP (reserved operand), NaN (not a number),
or closest equivalent. CRAY and IBM data types return 0.
4
|
|
CVT_RESULT_OVERFLOW
|
Conversion resulted in overflow.
4
|
|
CVT_RESULT_UNDERFLOW
|
Conversion resulted in underflow.
4
|
|
CVT_RESULT_INEXACT
|
Conversion resulted in a loss of precision.
4
|
1For IEEE data type conversions.
2For CRAY data type conversions.
3For IBM data type conversions.
4For all data type conversions.
See Also
Appendix A, Critical Floating-Point Values
ANSI/IEEE Std 754-1985, IEEE Standard for Binary Floating-Point
Arithmetic
Example
|
status = cvt_ftof( &big_x, CVT_BIG_ENDIAN_IEEE_T,
&little_x, CVT_IEEE_T, 0 );
|
This example converts the value pointed to by big_x, which is of type
IEEE Big Endian T Floating, to the IEEE Little Endian T Floating data
type. It stores the result in the location pointed to by little_x. No
conversion options are specified.
|
status = cvt_ftof(&x, CVT_VAX_D, &y, CVT_IEEE_T,
(CVT_FORCE_ALL_SPECIAL_VALUES | CVT_REPORT_ALL) );
|
This example converts the value pointed to by x, which is of type VAX D
Floating, to the IEEE Little Endian T Floating data type. It stores the
result in the location pointed to by y. Any special IEEE values that
would normally be generated will be removed. That is, NaN and
Denormalized results will be returned as zero and infinite results will
go to +- max_float. In addition, all recordable status conditions will
be reported.