 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
cvt_ftof(3)
NAME
cvt_ftof - Converts a floating-point data type to another supported
floating-point data type.
LIBRARY
Math Library (libm.a)
SYNOPSIS
#include <cvt.h>
int cvt_ftof(
void *input_val,
int input_type,
void *output_val,
int output_type,
int options);
DESCRIPTION
cvt_ftof() converts one floating-point data type to another. Input_val
points to the input value to be converted and output_val points to the
converted result. The conversion is subject to the options specified in
the options (bit field) argument. This function returns a bit field
indicating any status conditions.
Input_type and output_type identify the floating-point data type of
input_val and output_val as follows:
_________________________________________________________________
Input_type/Output_type Data Type Size
_________________________________________________________________
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 Single 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 incompatible 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 mode for
conversions to IEEE
data types. This
IEEE Std. 754
rounding mode
results in a
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 mode for
conversions to
non-IEEE data
types. Performs
"traditional" style
rounding. This
mode results in a
representable
output value
nearest to the
infinitely precise
result. If the two
nearest
representable
values are equally
near, the output
value is the
closest to either
positive infinity
or negative
infinity depending
on the sign of the
input value.
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
Force a
denormalized IEEE
output value to
zero. This option
is valid only for
conversions to IEEE
output values.
IEEE CVT_FORCE_INF_TO_MAX_FLOAT
Force a positive
IEEE infinite
output value to
+max_float and
force a negative
IEEE infinite
output value to
-max_float. This
option is valid
only for
conversions to IEEE
output values.
IEEE or VAX CVT_FORCE_INVALID_TO_ZERO
Force an invalid
IEEE NaN (not a
number) output
value or a VAX ROP
(reserved operand)
output value to
zero. This 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 Options 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.
______________________________________________________________________
The maximum representable floating-point values (max_float) for the
IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating,
Big_Endian_IEEE_S_Floating, Big_Endian_IEEE_T_Floating, and
Big_Endian_IEEE_X_Floating formats are:
_________________________________________________________________________
Data Type max_float Value
_________________________________________________________________________
S_FLOAT Decimal: 3.402823e38
T_FLOAT Decimal: 1.797693134862316e308
X_FLOAT Decimal: 1.189731495357231765085759326628007016196477e4932
_________________________________________________________________________
EXAMPLES
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 and stores the result in the location pointed to by little_x. No
conversion options are specified.
status = cvt_ftof( &big_x, CVT_BIG_ENDIAN_IEEE_T,
&little_x, CVT_IEEE_T, 0 );
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 and stores the
result in the location pointed to by y. Any special IEEE values which
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.
status = cvt_ftof(&x, CVT_VAX_D, &y, CVT_IEEE_T,
(CVT_FORCE_ALL_SPECIAL_VALUES | CVT_REPORT_ALL) );
RETURN VALUES
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 (Only reported if the
Condition Name CVT_REPORT_ALL option is selected)
________________________________________________________________
CVT_RESULT_INFINITE
Conversion produced an infinite
result. (For conversions to IEEE
data types.)
CVT_RESULT_DENORMALIZED
Conversion produced a denormalized
result. (For conversions to IEEE
data types.)
CVT_RESULT_OVERFLOW_RANGE
Conversion yielded an exponent >
60000 (8). (For Cray data type
conversions.)
CVT_RESULT_UNDERFLOW_RANGE
Conversion yielded an exponent <
20000 (8). (For Cray data type
conversions.)
CVT_RESULT_UNNORMALIZED
Conversion produced an
unnormalized result. (For IBM
data type conversions and reported
CVT_RESULT_INVALID
Conversion result is either ROP
(reserved operand), NaN (not a
number), or closest equivalent.
Cray and IBM data types return 0.
(For all data type conversions.)
CVT_RESULT_OVERFLOW
Conversion resulted in overflow.
(For all data type conversions.)
CVT_RESULT_UNDERFLOW
Conversion resulted in underflow.
(For all data type conversions.)
CVT_RESULT_INEXACT
Conversion resulted in a loss of
precision. (For all data type
conversions.)
________________________________________________________________
RELATED INFORMATION
ANSII/IEEE Std 754-1985, IEEE Standard for Binary Floating-Point Arithmetic
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|