usr/src/man/man3c/floating_to_decimal.3c

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH FLOATING_TO_DECIMAL 3C "Jun 7, 2005"
   7 .SH NAME
   8 floating_to_decimal, single_to_decimal, double_to_decimal, extended_to_decimal,
   9 quadruple_to_decimal \- convert floating-point value to decimal record
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <floatingpoint.h>
  14
  15 \fBvoid\fR \fBsingle_to_decimal\fR(\fBsingle *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR,
  16      \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBdouble_to_decimal\fR(\fBdouble *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR,
  22      \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBextended_to_decimal\fR(\fBextended *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR,
  28      \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBquadruple_to_decimal\fR(\fBquadruple *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR,
  34      \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR);
  35 .fi
  36
  37 .SH DESCRIPTION
  38 .sp
  39 .LP
  40 The \fBfloating_to_decimal\fR functions convert the floating-point value at
  41 \fI*px\fR into a decimal record at *\fIpd\fR, observing the modes specified in
  42 *\fIpm\fR and setting exceptions in *\fIps\fR. If there are no IEEE exceptions,
  43 *\fIps\fR will be zero.
  44 .sp
  45 .LP
  46 If *\fIpx\fR is zero, infinity, or NaN, then only \fIpd\fR\(->\fIsign\fR and
  47 \fIpd\fR\(->\fIfpclass\fR are set. Otherwise \fIpd\fR\(->\fIexponent\fR and
  48 \fIpd\fR\(->\fIds\fR are also set so that
  49 .sp
  50 .in +2
  51 .nf
  52 (sig)*(pd->ds)*10**(pd->exponent)
  53 .fi
  54 .in -2
  55
  56 .sp
  57 .LP
  58 is a correctly rounded approximation to *\fIpx\fR, where \fIsig\fR is +1 or
  59 \(mi1, depending upon whether \fIpd\fR\(->\fIsign\fR is  0 or \(mi1.
  60 \fIpd\fR\(->\fIds\fR has at least one and no more than
  61 \fBDECIMAL_STRING_LENGTH\fR-1 significant digits because one character is used
  62 to terminate the string with a null.
  63 .sp
  64 .LP
  65 \fIpd\fR\(->\fIds\fR is correctly rounded according to the IEEE rounding modes
  66 in \fIpm\fR\(->\fIrd\fR. *\fIps\fR has \fIfp_inexact\fR set if the result was
  67 inexact, and has \fIfp_overflow\fR set if the string result does not fit in
  68 \fIpd\fR\(->\fIds\fR because of the limitation \fBDECIMAL_STRING_LENGTH\fR.
  69 .sp
  70 .LP
  71 If \fIpm\fR\(->\fIdf\fR == \fIfloating_form\fR, then \fIpd\fR\(->\fIds\fR
  72 always contains \fIpm\fR\(->\fIndigits\fR significant digits. Thus if *\fIpx\fR
  73 == 12.34 and \fIpm\fR\(->\fIndigits\fR == 8, then \fIpd\fR\(->\fIds\fR will
  74 contain 12340000 and \fIpd\fR\(->\fIexponent\fR will contain \(mi6.
  75 .sp
  76 .LP
  77 If \fIpm\fR\(->\fIdf\fR == \fIfixed_form\fR and \fIpm\fR\(->\fIndigits\fR >= 0,
  78 then the decimal value is rounded at \fIpm\fR\(->\fIndigits\fR digits to the
  79 right of the decimal point. For example, if *\fIpx\fR == 12.34 and
  80 \fIpm\fR\(->\fIndigits\fR == 1, then \fIpd\fR\(->\fIds\fR will contain 123 and
  81 \fIpd\fR\(->\fIexponent\fR will be set to \(mi1.
  82 .sp
  83 .LP
  84 If \fIpm\fR\(->\fIdf\fR == \fIfixed_form\fR and \fIpm\fR\(->\fIndigits\fR< 0,
  85 then the decimal value is rounded at \(mi\fIpm\fR\(->\fIndigits\fR digits to
  86 the left of the decimal point, and \fIpd\fR\(->\fIds\fR is padded with trailing
  87 zeros up to the decimal point. For example, if *\fIpx\fR == 12.34 and
  88 \fIpm\fR\(->\fIn\fR digits == \(mi1, then \fIpd\fR\(->\fIds\fR will contain 10
  89 and \fIpd\fR\(->\fIexponent\fR will be set to 0.
  90 .sp
  91 .LP
  92 When \fIpm\fR\(->\fIdf\fR == \fIfixed_form\fR and the value to be converted is
  93 large enough that the  resulting string would contain more than
  94 \fBDECIMAL_STRING_LENGTH\fR\(mi1 digits, then the string placed in
  95 \fIpd\fR\(->\fIds\fR is limited to exactly \fBDECIMAL_STRING_LENGTH\fR-1 digits
  96 (by moving the place at which the value is rounded further left if need be),
  97 \fIpd\fR\(->\fIexponent\fR is adjusted accordingly and the overflow flag is set
  98 in *\fIps\fR.
  99 .sp
 100 .LP
 101 \fIpd->more\fR is not used.
 102 .sp
 103 .LP
 104 The \fBeconvert\fR(3C), \fBfconvert\fR(3C), \fBgconvert\fR(3C),
 105 \fBprintf\fR(3C), and \fBsprintf\fR(3C) functions all use
 106 \fBdouble_to_decimal()\fR.
 107 .SH ATTRIBUTES
 108 .sp
 109 .LP
 110 See \fBattributes\fR(5) for descriptions of the following attributes:
 111 .sp
 112
 113 .sp
 114 .TS
 115 box;
 116 c | c
 117 l | l .
 118 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 119 _
 120 MT-Level        MT-Safe
 121 .TE
 122
 123 .SH SEE ALSO
 124 .sp
 125 .LP
 126 \fBeconvert\fR(3C), \fBfconvert\fR(3C), \fBgconvert\fR(3C), \fBprintf\fR(3C),
 127 \fBsprintf\fR(3C), \fBattributes\fR(5)