'\"!  eqn | mmdoc
'\"macro stdmacro
.if n .pH g3c.decconv @(#)decconv	40.10 of 10/25/89
.\" Copyright 1989 AT&T
.EQ
delim $$
gfont 3
gsize 8
.EN
.nr X
.if \nX=0 .ds x} decconv 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} decconv 3C "C Programming Language Utilities"
.if \nX=2 .ds x} decconv 3C "" "\&"
.if \nX=3 .ds x} decconv "" "" "\&"
.TH \*(x}
.SH NAME
\f4decconv:\f1 \f4_s2dec\f1, \f4_d2dec\f1, \f4_dec2s\f1, \f4_dec2d\f1 \- convert between binary and decimal values
.SH SYNOPSIS
.ta .5i
.nf
\f4#include <ieeefp.h>
.sp .75
void _s2dec (float \(**x, decimal \(**d, int p);
.sp .75
void _d2dec (double \(**x, decimal \(**d, int p);
.sp .75
void _dec2s (decimal \(**d, float \(**x, int p);
.sp .75
void _dec2d (decimal \(**d, double \(**x, int p);
\f1
.SH DESCRIPTION
The \f4_s2dec\f1 function returns a decimal floating-point value,
given a pointer to a single-precision binary floating-point number
and a precision specification.
.PP
On input, the value of the \f4ilen\f1 field in the decimal 
should be set to tell how many decimal digits should be output 
in the mantissa for rounding purposes.
If the \f4ilen\f1 field is not in the 
range $ 1~\(<=~ilen~\(<=~9 $, a NaN is returned.
If the input binary value \f4x\f1 is a
NaN or infinity, the returned decimal \f4d\f1 will be a NaN
or infinity with the appropriate sign.
The exponential component of the returned decimal value
is always two digits.
The structure \f4decimal\f1 is defined
in the \f4ieeefp.h\f1 header file.
.PP
The parameter $ p~( 0~\(<=~p~\(<=~ilen ) $
specifies how many of the digits in the output decimal mantissa 
string are to be considered to be to the right of the
implicit decimal point.
If \f4p\f1 is out of range, a NaN is returned.
.PP
The \f4_d2dec\f1 function works like the \f4_s2dec\f1 function except that it
takes a pointer to a double-precision value for \f4x\f1.
The \f4ilen\f1 field must be in the 
range of $ 1~\(<=~ilen~\(<=~17 $,
and the exponential component of the returned decimal
will contain three digits.
.PP
The \f4_dec2s\f1 function returns a single-precision binary
floating-point value, given a decimal value
and a precision specification.
.PP
The parameter $ p~( 0~\(<=~p~\(<=~ilen ) $
tells how many of the digits in the mantissa string are
to be considered to be to the right of an implicit decimal point.
.PP
Because the decimal format can represent a larger range
of numbers than the binary formats,
this conversion may overflow or underflow.
Upon overflow or underflow, a signed infinity (signed zero) is
returned, and the appropriate sticky bit is set.
.PP
The mantissa and exponent strings may contain leading zero
characters.  But, once all leading 0 characters are removed,
the mantissa string should have a length $ > 0 $ and $ \(<= 9 $.
The exponent string should have a length $ > 0 $ and $ \(<= 2 $.
The special case of $ d~\(eq\|\(eq~0 $ (decimal) is detected, in which
case the trailing 0 characters in the string are not removed.
.PP
The \f4_dec2d\f1 function is analogous to the \f4_dec2s\f1 function
except that it returns a double-precision value.
After leading 0 characters are removed, the mantissa string
should contain no more than 17 digits and the exponent string
should contain no more than three digits.
.PP
Rounding is performed according to the current rounding mode.
The default is round-to-nearest.
.PP
Calling these functions may result in the following exceptions:
overflow, underflow, inexact result, invalid operation.
.SH "SEE ALSO"
\f4fpgetround\f1(3C).
.br
The ``Floating Point Operations'' chapter in the
\f2Programmer's Guide: ANSI C and Programming Support Tools\f1.
.Ee
