share/man/man3c/econvert.3c

   1 '\" te
   2 .\"  Copyright (c) 1999, 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 ECONVERT 3C "April 9, 2016"
   7 .SH NAME
   8 econvert, fconvert, gconvert, seconvert, sfconvert, sgconvert, qeconvert,
   9 qfconvert, qgconvert \- output conversion
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <floatingpoint.h>
  14
  15 \fBchar *\fR\fBeconvert\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR,
  16      \fBchar *\fR\fIbuf\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBchar *\fR\fBfconvert\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR,
  22      \fBchar *\fR\fIbuf\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBchar *\fR\fBgconvert\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint\fR \fItrailing\fR, \fBchar *\fR\fIbuf\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBchar *\fR\fBseconvert\fR(\fBsingle *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR,
  33      \fBchar *\fR\fIbuf\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBchar *\fR\fBsfconvert\fR(\fBsingle *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR,
  39      \fBchar *\fR\fIbuf\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBchar *\fR\fBsgconvert\fR(\fBsingle *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint\fR \fItrailing\fR, \fBchar *\fR\fIbuf\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBchar *\fR\fBqeconvert\fR(\fBquadruple *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR,
  50      \fBchar *\fR\fIbuf\fR);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBchar *\fR\fBqfconvert\fR(\fBquadruple *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR
  56      \fBchar *\fR\fIbuf\fR);
  57 .fi
  58
  59 .LP
  60 .nf
  61 \fBchar *\fR\fBqgconvert\fR(\fBquadruple *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint\fR \fItrailing\fR, \fBchar *\fR\fIbuf\fR);
  62 .fi
  63
  64 .SH DESCRIPTION
  65 .LP
  66 The \fBeconvert()\fR function converts the \fIvalue\fR to a null-terminated
  67 string of \fIndigit\fR \fBASCII\fR digits in \fIbuf\fR and returns a pointer to
  68 \fIbuf\fR. \fIbuf\fR should contain at least \fIndigit+1\fR characters. The
  69 position of the decimal point relative to the beginning of the string is stored
  70 indirectly through \fIdecpt\fR. Thus \fIbuf\fR == "314" and \fI*decpt\fR == 1
  71 corresponds to the numerical value 3.14, while \fIbuf\fR == "314" and
  72 \fI*decpt\fR == \(mi1 corresponds to the numerical value .0314. If the sign of
  73 the result is negative, the word pointed to by \fIsign\fR is nonzero; otherwise
  74 it is zero. The least significant digit is rounded.
  75 .sp
  76 .LP
  77 The \fBfconvert()\fR function works much like \fBeconvert()\fR, except that the
  78 correct digit has been rounded as if for  \fBsprintf(%w.nf)\fR output with
  79 \fIn\fR=\fIndigit\fR digits to the right of the decimal point. \fIndigit\fR can
  80 be negative to indicate rounding to the left of the decimal point. The return
  81 value is a pointer to \fIbuf\fR. \fIbuf\fR should contain at least
  82 \fI310+max(0,ndigit)\fR characters to accommodate any double-precision
  83 \fIvalue\fR.
  84 .sp
  85 .LP
  86 The \fBgconvert()\fR function converts the \fIvalue\fR to a null-terminated
  87 \fBASCII\fR string in \fIbuf\fR and returns a pointer to \fIbuf\fR. It produces
  88 \fIndigit\fR significant digits in fixed-decimal format, like
  89 \fBsprintf(%w.nf)\fR, if possible, and otherwise in floating-decimal format,
  90 like  \fBsprintf(%w.ne)\fR; in either case \fIbuf\fR is ready for printing,
  91 with sign and exponent. The result corresponds to that obtained by
  92 .sp
  93 .in +2
  94 .nf
  95 (void) sprintf(buf,``%w.ng'',value) ;
  96 .fi
  97 .in -2
  98
  99 .sp
 100 .LP
 101 If \fItrailing\fR = 0, trailing zeros and a trailing point are suppressed, as
 102 in  \fBsprintf(%g)\fR. If \fItrailing\fR != 0, trailing zeros and a trailing
 103 point are retained, as in  \fBsprintf(%#g)\fR.
 104 .sp
 105 .LP
 106 The \fBseconvert()\fR, \fBsfconvert()\fR, and \fBsgconvert()\fR functions are
 107 single-precision versions of these functions, and are more efficient than the
 108 corresponding double-precision versions. A pointer rather than the value itself
 109 is passed to avoid C's usual conversion of single-precision arguments to
 110 double.
 111 .sp
 112 .LP
 113 The \fBqeconvert()\fR, \fBqfconvert()\fR, and \fBqgconvert()\fR functions are
 114 quadruple-precision versions of these functions. The \fBqfconvert()\fR function
 115 can overflow the  \fIdecimal_record\fR field  \fIds\fR if \fIvalue\fR is too
 116 large. In that case, \fIbuf\fR[0] is set to zero.
 117 .sp
 118 .LP
 119 The \fBecvt()\fR, \fBfcvt()\fR and \fBgcvt()\fR functions are versions of
 120 \fBeconvert()\fR, \fBfconvert()\fR, and \fBgconvert()\fR, respectively, that
 121 are documented on the \fBecvt\fR(3C) manual page.  They constitute the default
 122 implementation of these functions and conform to the X/Open CAE Specification,
 123 System Interfaces and Headers, Issue 4, Version 2.
 124 .SH USAGE
 125 .LP
 126 \fBIEEE\fR Infinities and NaNs are treated similarly by these functions.
 127 ``NaN'' is returned for NaN, and ``Inf'' or ``Infinity'' for Infinity.  The
 128 longer form is produced when \fIndigit\fR >= 8.
 129 .SH ATTRIBUTES
 130 .LP
 131 See \fBattributes\fR(5) for descriptions of the following attributes:
 132 .sp
 133
 134 .sp
 135 .TS
 136 box;
 137 c | c
 138 l | l .
 139 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 140 _
 141 MT-Level        MT-Safe
 142 .TE
 143
 144 .SH SEE ALSO
 145 .LP
 146 \fBecvt\fR(3C), \fBsprintf\fR(3C), \fBattributes\fR(5)