[Contents] [Previous Section] [Next Section] [Index]

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.

[Contents] [Previous Section] [Next Section] [Index]