| blob | 7b0552e454c473d948b71f1035e141e1ef52abfa |
1 '\" te
2 .\" Copyright (c) 2003. 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 STRING_TO_DECIMAL 3C "Oct 1, 2003"
7 .SH NAME
8 string_to_decimal, file_to_decimal, func_to_decimal \- parse characters into
9 decimal record
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <floatingpoint.h>
15 \fBvoid\fR \fBstring_to_decimal\fR(\fBchar **\fR\fIpc\fR, \fBint\fR \fInmax\fR,
16 \fBint\fR \fIfortran_conventions\fR, \fBdecimal_record *\fR\fIpd\fR,
17 \fBenum decimal_string_form *\fR\fIpform\fR, \fBchar **\fR\fIpechar\fR);
18 .fi
20 .LP
21 .nf
22 \fBvoid\fR \fBfunc_to_decimal\fR(\fBchar **\fR\fIpc\fR, \fBint\fR \fInmax\fR,
23 \fBint\fR \fIfortran_conventions\fR, \fBdecimal_record *\fR\fIpd\fR,
24 \fBenum decimal_string_form *\fR\fIpform\fR, \fBchar **\fR\fIpechar\fR,
25 \fBint (*\fR\fIpget\fR)(void), \fBint *\fR\fIpnread\fR, \fBint (*\fR\fIpunget\fR)(int \fIc\fR));
26 .fi
28 .LP
29 .nf
30 #include <stdio.h>
32 \fBvoid\fR \fBfile_to_decimal\fR(\fBchar **\fR\fIpc\fR, \fBint\fR \fInmax\fR,
33 \fBint\fR \fIfortran_conventions\fR, \fBdecimal_record *\fR\fIpd\fR,
34 \fBenum decimal_string_form *\fR\fIpform\fR, \fBchar **\fR\fIpechar\fR,
35 \fBFILE *\fR\fIpf\fR, \fBint *\fR\fIpnread\fR);
36 .fi
38 .SH DESCRIPTION
39 .sp
40 .LP
41 These functions attempt to parse a numeric token from at most \fInmax\fR
42 characters read from a string **\fIpc\fR, a file *\fIpf\fR, or function
43 (*\fIpget\fR). They set the decimal record *\fIpd\fR to reflect the value of
44 the numeric token recognized and set *\fIpform\fR and *\fIpechar\fR to indicate
45 its form.
46 .sp
47 .LP
48 The accepted forms for the numeric token consist of an initial, possibly empty,
49 sequence of white-space characters, as defined by \fBisspace\fR(3C), followed
50 by a subject sequence representing a numeric value, infinity, or NaN. The
51 subject sequence consists of an optional plus or minus sign followed by one of
52 the following:
53 .RS +4
54 .TP
55 .ie t \(bu
56 .el o
57 a non-empty sequence of decimal digits optionally containing a decimal point
58 character, then an optional exponent part
59 .RE
60 .RS +4
61 .TP
62 .ie t \(bu
63 .el o
64 one of INF or INFINITY, ignoring case
65 .RE
66 .RS +4
67 .TP
68 .ie t \(bu
69 .el o
70 one of NAN or NAN(\fIstring\fR), ignoring case in the NAN part; \fIstring\fR
71 can be any sequence of characters not containing ')' (right parenthesis)
72 or '\e0' (null).
73 .RE
74 .sp
75 .LP
76 The \fIfortran_conventions\fR argument provides additional control over the set
77 of accepted forms. It must be one of the following values:
78 .sp
79 .ne 2
80 .na
81 \fB0\fR
82 .ad
83 .RS 5n
84 no Fortran conventions
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB1\fR
91 .ad
92 .RS 5n
93 Fortran list-directed input conventions
94 .RE
96 .sp
97 .ne 2
98 .na
99 \fB2\fR
100 .ad
101 .RS 5n
102 Fortran formatted input conventions, blanks are ignored
103 .RE
105 .sp
106 .ne 2
107 .na
108 \fB3\fR
109 .ad
110 .RS 5n
111 Fortran formatted input conventions, blanks are interpreted as zeroes
112 .RE
114 .sp
115 .LP
116 When \fIfortran_conventions\fR is zero, the decimal point character is the
117 current locale's decimal point character, and the exponent part consists of the
118 letter \fBE\fR or \fBe\fR followed by an optional sign and a non-empty string
119 of decimal digits.
120 .sp
121 .LP
122 When \fIfortran_conventions\fR is non-zero, the decimal point character is "."
123 (period), and the exponent part consists of either a sign or one of the letters
124 \fBE\fR, \fBe\fR, \fBD\fR, \fBd\fR, \fBQ\fR, or \fBq\fR followed by an optional
125 sign, then a non-empty string of decimal digits.
126 .sp
127 .LP
128 When \fIfortran_conventions\fR is \fB2\fR or \fB3\fR, blanks can appear in the
129 digit strings for the integer, fraction, and exponent parts, between the
130 exponent delimiter and optional exponent sign, and after an INF, INFINITY, NAN,
131 or NAN(\fIstring\fR). When \fIfortran_conventions\fR is \fB2\fR, all blanks
132 are ignored. When \fIfortran_conventions\fR is \fB3\fR, blanks in digit
133 strings are interpreted as zeros and other blanks are ignored.
134 .sp
135 .LP
136 The following table summarizes the accepted forms and shows the corresponding
137 values to which *\fIpform\fR and \fIpd\fR->\fBfpclass\fR are set. Here
138 \fIdigits\fR represents any string of decimal digits, "." (period) stands for
139 the decimal point character, and \fIexponent\fR represents the exponent part as
140 defined above. Numbers in brackets refer to the notes following the table.
141 .sp
143 .sp
144 .TS
145 c c c
146 l l l .
147 form *\fIpform\fR pd->\fBfpclass\fR
148 _
149 all white space [1] \fBwhitespace_form\fR \fBfp_zero\fR
150 \fIdigits\fR \fBfixed_int_form\fR \fBfp_normal\fR [2]
151 \fIdigits\fR. \fBfixed_intdot_form\fR \fBfp_normal\fR [2]
152 \&.\fIdigits\fR \fBfixed_dotfrac_form\fR \fBfp_normal\fR [2]
153 \fIdigits\fR.\fIdigits\fR \fBfixed_intdotfrac_form\fR \fBfp_normal\fR [2]
154 \fIdigits\fR \fIexponent\fR \fBfloating_int_form\fR \fBfp_normal\fR [2]
155 \fIdigits\fR. \fIexponent\fR \fBfloating_intdot_form\fR \fBfp_normal\fR [2]
156 \&.digits \fIexponent\fR \fBfloating_dotfrac_form\fR \fBfp_normal\fR [2]
157 \fIdigits\fR.\fIdigits\fR \fIexponent\fR \fBfloating_intdotfrac_form\fR \fBfp_normal\fR [2]
158 INF \fBinf_form\fR \fBfp_infinity\fR
159 INFINITY \fBinfinity_form\fR \fBfp_infinity\fR
160 NAN \fBnan_form\fR \fBfp_quiet\fR
161 NAN(\fIstring\fR) \fBnanstring_form\fR \fBfp_quiet\fR
162 none of the above \fBinvalid_form\fR \fBfp_signaling\fR
163 .TE
165 .sp
166 .LP
167 Notes:
168 .RS +4
169 .TP
170 1.
171 The \fBwhitespace_form\fR is accepted only when \fIfortran_conventions\fR is
172 2 or 3 and is interpreted as zero.
173 .RE
174 .RS +4
175 .TP
176 2.
177 For all numeric forms, \fIpd\fR->\fBfpclass\fR is set to \fBfp_normal\fR if
178 any non-zero digits appear in the integer or fraction parts, and otherwise
179 \fIpd\fR->\fBfpclass\fR is set to \fBfp_zero\fR.
180 .RE
181 .sp
182 .LP
183 If the accepted token has one of the numeric forms and represents a non-zero
184 number \fIx\fR, its significant digits are stored in \fIpd\fR->\fBds\fR.
185 Leading and trailing zeroes and the radix point are omitted.
186 \fIpd\fR->\fBsign\fR and \fIpd\fR->\fBexponent\fR are set so that if \fIm\fR is
187 the integer represented by pd->\fBds\fR,
188 .sp
189 .in +2
190 .nf
191 \(mi1**(pd->sign) * m * 10**(pd->exponent)
192 .fi
193 .in -2
195 .sp
196 .LP
197 approximates \fIx\fR to at least 511 significant digits. \fIpd\fR->\fBmore\fR
198 is set to 1 if this approximation is not exact (that is, the accepted token
199 contains additional non-zero digits beyond those copied to \fIpd\fR->\fBds\fR)
200 and to 0 otherwise.
201 .sp
202 .LP
203 If the accepted token has the NAN(\fIstring\fR) form, up to 511 characters from
204 the string part are copied to \fIpd\fR->\fBds\fR.
205 .sp
206 .LP
207 \fIpd\fR->\fBds\fR is always terminated by a null byte, and
208 \fIpd\fR->\fBndigits\fR is set to the length of the string stored in
209 \fIpd\fR->\fBds\fR.
210 .sp
211 .LP
212 On entry, *\fIpc\fR points to the beginning of a character string buffer. The
213 \fBstring_to_decimal()\fR function reads characters from this buffer until
214 either enough characters are read to delimit the accepted token (for example, a
215 null character marking the end of the string is found) or the limit of
216 \fInmax\fR characters is reached. The \fBfile_to_decimal()\fR function reads
217 characters from the file *\fIpf\fR and stores them in the buffer. The
218 \fBfunc_to_decimal()\fR function reads characters one at a time by calling the
219 function (*\fIpget\fR)() and stores them in the buffer; (*\fIpget\fR)() must
220 return integer values in the range \(mi1 to 255, where \(mi1 is interpreted as
221 EOF and 0, ..., 255 are interpreted as \fBunsigned char\fR values. Both
222 \fBfile_to_decimal()\fR and \fBfunc_to_decimal()\fR read characters until
223 either enough characters are read to delimit the accepted token, EOF is
224 encountered, or the limit of \fInmax\fR characters is reached. These functions,
225 therefore, typically read one or more additional characters beyond the end of
226 the accepted token and attempt to push back any excess characters read.
227 Provided that the \fIpunget\fR argument is not \fINULL\fR,
228 \fBfunc_to_decimal()\fR pushes back characters one at a time by calling
229 (*\fIpunget\fR)(\fIc\fR), where \fIc\fR is an integer in the range 0 to 255
230 corresponding to a value previously read via (*\fIpget\fR)(). After pushing
231 back as many excess characters as possible, \fBfile_to_decimal()\fR and
232 \fBfunc_to_decimal()\fR store a null byte in the buffer following the last
233 character read and not pushed back and set *\fIpnread\fR to the number of
234 characters stored in the buffer prior to this null byte. Since these functions
235 can read up to \fInmax\fR characters, the buffer must be large enough to hold
236 \fInmax\fR + 1.
237 .sp
238 .LP
239 On exit, *\fIpc\fR points to the next character in the buffer past the last one
240 that was accepted as part of the numeric token. If no valid token is found,
241 *\fIpc\fR is unchanged. If \fBfile_to_decimal()\fR and \fBfunc_to_decimal()\fR
242 successfully push back all unused characters, *\fIpc\fR points to the null byte
243 stored in the buffer following the last character read and not pushed back.
244 .sp
245 .LP
246 If the accepted token contains an exponent part, *\fIpechar\fR is set to point
247 to the position in the buffer where the first character of the exponent field
248 is stored. If the accepted token does not contain an exponent part,
249 *\fIpechar\fR is set to \fINULL\fR.
250 .SH USAGE
251 .sp
252 .LP
253 If the \fB_IOWRT\fR flag is set in *\fIpf\fR, \fBfile_to_decimal()\fR reads
254 characters directly from the file buffer until a null character is found. (The
255 \fB_IOWRT\fR flag should only be set when \fBfile_to_decimal()\fR is called
256 from \fBsscanf\fR(3C).) Otherwise, \fBfile_to_decimal()\fR uses
257 \fBgetc_unlocked\fR(3C), so it is not MT-safe unless the caller holds the
258 stream lock.
259 .SH ATTRIBUTES
260 .sp
261 .LP
262 See \fBattributes\fR(5) for descriptions of the following attributes:
263 .sp
265 .sp
266 .TS
267 box;
268 c | c
269 l | l .
270 ATTRIBUTE TYPE ATTRIBUTE VALUE
271 _
272 MT-Level MT-Safe with exceptions
273 .TE
275 .SH SEE ALSO
276 .sp
277 .LP
278 \fBctype\fR(3C), \fBdecimal_to_floating\fR(3C), \fBgetc_unlocked\fR(3C),
279 \fBisspace\fR(3C), \fBlocaleconv\fR(3C), \fBscanf\fR(3C), \fBsetlocale\fR(3C),
280 \fBstrtod\fR(3C), \fBungetc\fR(3C), \fBattributes\fR(5)