cvt_ftof(3) — Subroutines
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