]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
1 | @node Arithmetic, Date and Time, Mathematics, Top |
2 | @chapter Low-Level Arithmetic Functions | |
3 | ||
4 | This chapter contains information about functions for doing basic | |
5 | arithmetic operations, such as splitting a float into its integer and | |
6 | fractional parts. These functions are declared in the header file | |
7 | @file{math.h}. | |
8 | ||
9 | @menu | |
10 | * Not a Number:: Making NaNs and testing for NaNs. | |
11 | * Predicates on Floats:: Testing for infinity and for NaNs. | |
12 | * Absolute Value:: Absolute value functions. | |
13 | * Normalization Functions:: Hacks for radix-2 representations. | |
6d52618b | 14 | * Rounding and Remainders:: Determining the integer and |
28f540f4 RM |
15 | fractional parts of a float. |
16 | * Integer Division:: Functions for performing integer | |
17 | division. | |
18 | * Parsing of Numbers:: Functions for ``reading'' numbers | |
19 | from strings. | |
20 | @end menu | |
21 | ||
22 | @node Not a Number | |
23 | @section ``Not a Number'' Values | |
24 | @cindex NaN | |
25 | @cindex not a number | |
26 | @cindex IEEE floating point | |
27 | ||
28 | The IEEE floating point format used by most modern computers supports | |
29 | values that are ``not a number''. These values are called @dfn{NaNs}. | |
30 | ``Not a number'' values result from certain operations which have no | |
31 | meaningful numeric result, such as zero divided by zero or infinity | |
32 | divided by infinity. | |
33 | ||
34 | One noteworthy property of NaNs is that they are not equal to | |
35 | themselves. Thus, @code{x == x} can be 0 if the value of @code{x} is a | |
36 | NaN. You can use this to test whether a value is a NaN or not: if it is | |
37 | not equal to itself, then it is a NaN. But the recommended way to test | |
38 | for a NaN is with the @code{isnan} function (@pxref{Predicates on Floats}). | |
39 | ||
40 | Almost any arithmetic operation in which one argument is a NaN returns | |
41 | a NaN. | |
42 | ||
43 | @comment math.h | |
44 | @comment GNU | |
45 | @deftypevr Macro double NAN | |
46 | An expression representing a value which is ``not a number''. This | |
47 | macro is a GNU extension, available only on machines that support ``not | |
48 | a number'' values---that is to say, on all machines that support IEEE | |
49 | floating point. | |
50 | ||
51 | You can use @samp{#ifdef NAN} to test whether the machine supports | |
52 | NaNs. (Of course, you must arrange for GNU extensions to be visible, | |
53 | such as by defining @code{_GNU_SOURCE}, and then you must include | |
54 | @file{math.h}.) | |
55 | @end deftypevr | |
56 | ||
57 | @node Predicates on Floats | |
58 | @section Predicates on Floats | |
59 | ||
60 | @pindex math.h | |
61 | This section describes some miscellaneous test functions on doubles. | |
62 | Prototypes for these functions appear in @file{math.h}. These are BSD | |
63 | functions, and thus are available if you define @code{_BSD_SOURCE} or | |
64 | @code{_GNU_SOURCE}. | |
65 | ||
66 | @comment math.h | |
67 | @comment BSD | |
68 | @deftypefun int isinf (double @var{x}) | |
69 | This function returns @code{-1} if @var{x} represents negative infinity, | |
70 | @code{1} if @var{x} represents positive infinity, and @code{0} otherwise. | |
71 | @end deftypefun | |
72 | ||
73 | @comment math.h | |
74 | @comment BSD | |
75 | @deftypefun int isnan (double @var{x}) | |
76 | This function returns a nonzero value if @var{x} is a ``not a number'' | |
77 | value, and zero otherwise. (You can just as well use @code{@var{x} != | |
78 | @var{x}} to get the same result). | |
79 | @end deftypefun | |
80 | ||
81 | @comment math.h | |
82 | @comment BSD | |
83 | @deftypefun int finite (double @var{x}) | |
84 | This function returns a nonzero value if @var{x} is finite or a ``not a | |
85 | number'' value, and zero otherwise. | |
86 | @end deftypefun | |
87 | ||
88 | @comment math.h | |
89 | @comment BSD | |
90 | @deftypefun double infnan (int @var{error}) | |
91 | This function is provided for compatibility with BSD. The other | |
92 | mathematical functions use @code{infnan} to decide what to return on | |
93 | occasion of an error. Its argument is an error code, @code{EDOM} or | |
94 | @code{ERANGE}; @code{infnan} returns a suitable value to indicate this | |
95 | with. @code{-ERANGE} is also acceptable as an argument, and corresponds | |
96 | to @code{-HUGE_VAL} as a value. | |
97 | ||
98 | In the BSD library, on certain machines, @code{infnan} raises a fatal | |
99 | signal in all cases. The GNU library does not do likewise, because that | |
f65fd747 | 100 | does not fit the @w{ISO C} specification. |
28f540f4 RM |
101 | @end deftypefun |
102 | ||
103 | @strong{Portability Note:} The functions listed in this section are BSD | |
104 | extensions. | |
105 | ||
106 | @node Absolute Value | |
107 | @section Absolute Value | |
108 | @cindex absolute value functions | |
109 | ||
110 | These functions are provided for obtaining the @dfn{absolute value} (or | |
111 | @dfn{magnitude}) of a number. The absolute value of a real number | |
112 | @var{x} is @var{x} is @var{x} is positive, @minus{}@var{x} if @var{x} is | |
113 | negative. For a complex number @var{z}, whose real part is @var{x} and | |
114 | whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt | |
115 | (@var{x}*@var{x} + @var{y}*@var{y})}}. | |
116 | ||
117 | @pindex math.h | |
118 | @pindex stdlib.h | |
119 | Prototypes for @code{abs} and @code{labs} are in @file{stdlib.h}; | |
120 | @code{fabs} and @code{cabs} are declared in @file{math.h}. | |
121 | ||
122 | @comment stdlib.h | |
f65fd747 | 123 | @comment ISO |
28f540f4 RM |
124 | @deftypefun int abs (int @var{number}) |
125 | This function returns the absolute value of @var{number}. | |
126 | ||
127 | Most computers use a two's complement integer representation, in which | |
128 | the absolute value of @code{INT_MIN} (the smallest possible @code{int}) | |
129 | cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined. | |
130 | @end deftypefun | |
131 | ||
132 | @comment stdlib.h | |
f65fd747 | 133 | @comment ISO |
28f540f4 RM |
134 | @deftypefun {long int} labs (long int @var{number}) |
135 | This is similar to @code{abs}, except that both the argument and result | |
136 | are of type @code{long int} rather than @code{int}. | |
137 | @end deftypefun | |
138 | ||
139 | @comment math.h | |
f65fd747 | 140 | @comment ISO |
28f540f4 RM |
141 | @deftypefun double fabs (double @var{number}) |
142 | This function returns the absolute value of the floating-point number | |
143 | @var{number}. | |
144 | @end deftypefun | |
145 | ||
146 | @comment math.h | |
147 | @comment BSD | |
148 | @deftypefun double cabs (struct @{ double real, imag; @} @var{z}) | |
149 | The @code{cabs} function returns the absolute value of the complex | |
150 | number @var{z}, whose real part is @code{@var{z}.real} and whose | |
151 | imaginary part is @code{@var{z}.imag}. (See also the function | |
152 | @code{hypot} in @ref{Exponents and Logarithms}.) The value is: | |
153 | ||
154 | @smallexample | |
155 | sqrt (@var{z}.real*@var{z}.real + @var{z}.imag*@var{z}.imag) | |
156 | @end smallexample | |
157 | @end deftypefun | |
158 | ||
159 | @node Normalization Functions | |
160 | @section Normalization Functions | |
161 | @cindex normalization functions (floating-point) | |
162 | ||
163 | The functions described in this section are primarily provided as a way | |
164 | to efficiently perform certain low-level manipulations on floating point | |
165 | numbers that are represented internally using a binary radix; | |
166 | see @ref{Floating Point Concepts}. These functions are required to | |
167 | have equivalent behavior even if the representation does not use a radix | |
168 | of 2, but of course they are unlikely to be particularly efficient in | |
169 | those cases. | |
170 | ||
171 | @pindex math.h | |
172 | All these functions are declared in @file{math.h}. | |
173 | ||
174 | @comment math.h | |
f65fd747 | 175 | @comment ISO |
28f540f4 RM |
176 | @deftypefun double frexp (double @var{value}, int *@var{exponent}) |
177 | The @code{frexp} function is used to split the number @var{value} | |
178 | into a normalized fraction and an exponent. | |
179 | ||
180 | If the argument @var{value} is not zero, the return value is @var{value} | |
181 | times a power of two, and is always in the range 1/2 (inclusive) to 1 | |
182 | (exclusive). The corresponding exponent is stored in | |
183 | @code{*@var{exponent}}; the return value multiplied by 2 raised to this | |
184 | exponent equals the original number @var{value}. | |
185 | ||
186 | For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and | |
187 | stores @code{4} in @code{exponent}. | |
188 | ||
189 | If @var{value} is zero, then the return value is zero and | |
190 | zero is stored in @code{*@var{exponent}}. | |
191 | @end deftypefun | |
192 | ||
193 | @comment math.h | |
f65fd747 | 194 | @comment ISO |
28f540f4 RM |
195 | @deftypefun double ldexp (double @var{value}, int @var{exponent}) |
196 | This function returns the result of multiplying the floating-point | |
197 | number @var{value} by 2 raised to the power @var{exponent}. (It can | |
198 | be used to reassemble floating-point numbers that were taken apart | |
199 | by @code{frexp}.) | |
200 | ||
201 | For example, @code{ldexp (0.8, 4)} returns @code{12.8}. | |
202 | @end deftypefun | |
203 | ||
204 | The following functions which come from BSD provide facilities | |
205 | equivalent to those of @code{ldexp} and @code{frexp}: | |
206 | ||
207 | @comment math.h | |
208 | @comment BSD | |
209 | @deftypefun double scalb (double @var{value}, int @var{exponent}) | |
210 | The @code{scalb} function is the BSD name for @code{ldexp}. | |
211 | @end deftypefun | |
212 | ||
213 | @comment math.h | |
214 | @comment BSD | |
215 | @deftypefun double logb (double @var{x}) | |
216 | This BSD function returns the integer part of the base-2 logarithm of | |
217 | @var{x}, an integer value represented in type @code{double}. This is | |
218 | the highest integer power of @code{2} contained in @var{x}. The sign of | |
219 | @var{x} is ignored. For example, @code{logb (3.5)} is @code{1.0} and | |
220 | @code{logb (4.0)} is @code{2.0}. | |
221 | ||
222 | When @code{2} raised to this power is divided into @var{x}, it gives a | |
223 | quotient between @code{1} (inclusive) and @code{2} (exclusive). | |
224 | ||
225 | If @var{x} is zero, the value is minus infinity (if the machine supports | |
226 | such a value), or else a very small number. If @var{x} is infinity, the | |
227 | value is infinity. | |
228 | ||
229 | The value returned by @code{logb} is one less than the value that | |
230 | @code{frexp} would store into @code{*@var{exponent}}. | |
231 | @end deftypefun | |
232 | ||
233 | @comment math.h | |
234 | @comment BSD | |
235 | @deftypefun double copysign (double @var{value}, double @var{sign}) | |
236 | The @code{copysign} function returns a value whose absolute value is the | |
237 | same as that of @var{value}, and whose sign matches that of @var{sign}. | |
238 | This is a BSD function. | |
239 | @end deftypefun | |
240 | ||
241 | @node Rounding and Remainders | |
242 | @section Rounding and Remainder Functions | |
243 | @cindex rounding functions | |
244 | @cindex remainder functions | |
245 | @cindex converting floats to integers | |
246 | ||
247 | @pindex math.h | |
248 | The functions listed here perform operations such as rounding, | |
249 | truncation, and remainder in division of floating point numbers. Some | |
250 | of these functions convert floating point numbers to integer values. | |
251 | They are all declared in @file{math.h}. | |
252 | ||
253 | You can also convert floating-point numbers to integers simply by | |
254 | casting them to @code{int}. This discards the fractional part, | |
255 | effectively rounding towards zero. However, this only works if the | |
256 | result can actually be represented as an @code{int}---for very large | |
257 | numbers, this is impossible. The functions listed here return the | |
258 | result as a @code{double} instead to get around this problem. | |
259 | ||
260 | @comment math.h | |
f65fd747 | 261 | @comment ISO |
28f540f4 RM |
262 | @deftypefun double ceil (double @var{x}) |
263 | The @code{ceil} function rounds @var{x} upwards to the nearest integer, | |
264 | returning that value as a @code{double}. Thus, @code{ceil (1.5)} | |
265 | is @code{2.0}. | |
266 | @end deftypefun | |
267 | ||
268 | @comment math.h | |
f65fd747 | 269 | @comment ISO |
28f540f4 RM |
270 | @deftypefun double floor (double @var{x}) |
271 | The @code{ceil} function rounds @var{x} downwards to the nearest | |
272 | integer, returning that value as a @code{double}. Thus, @code{floor | |
273 | (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}. | |
274 | @end deftypefun | |
275 | ||
276 | @comment math.h | |
277 | @comment BSD | |
278 | @deftypefun double rint (double @var{x}) | |
279 | This function rounds @var{x} to an integer value according to the | |
280 | current rounding mode. @xref{Floating Point Parameters}, for | |
281 | information about the various rounding modes. The default | |
282 | rounding mode is to round to the nearest integer; some machines | |
283 | support other modes, but round-to-nearest is always used unless | |
284 | you explicit select another. | |
285 | @end deftypefun | |
286 | ||
287 | @comment math.h | |
f65fd747 | 288 | @comment ISO |
28f540f4 RM |
289 | @deftypefun double modf (double @var{value}, double *@var{integer-part}) |
290 | This function breaks the argument @var{value} into an integer part and a | |
291 | fractional part (between @code{-1} and @code{1}, exclusive). Their sum | |
292 | equals @var{value}. Each of the parts has the same sign as @var{value}, | |
293 | so the rounding of the integer part is towards zero. | |
294 | ||
295 | @code{modf} stores the integer part in @code{*@var{integer-part}}, and | |
296 | returns the fractional part. For example, @code{modf (2.5, &intpart)} | |
297 | returns @code{0.5} and stores @code{2.0} into @code{intpart}. | |
298 | @end deftypefun | |
299 | ||
300 | @comment math.h | |
f65fd747 | 301 | @comment ISO |
28f540f4 RM |
302 | @deftypefun double fmod (double @var{numerator}, double @var{denominator}) |
303 | This function computes the remainder from the division of | |
304 | @var{numerator} by @var{denominator}. Specifically, the return value is | |
305 | @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n} | |
306 | is the quotient of @var{numerator} divided by @var{denominator}, rounded | |
307 | towards zero to an integer. Thus, @w{@code{fmod (6.5, 2.3)}} returns | |
308 | @code{1.9}, which is @code{6.5} minus @code{4.6}. | |
309 | ||
310 | The result has the same sign as the @var{numerator} and has magnitude | |
311 | less than the magnitude of the @var{denominator}. | |
312 | ||
313 | If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to | |
314 | @code{EDOM}. | |
315 | @end deftypefun | |
316 | ||
317 | @comment math.h | |
318 | @comment BSD | |
319 | @deftypefun double drem (double @var{numerator}, double @var{denominator}) | |
320 | The function @code{drem} is like @code{fmod} except that it rounds the | |
321 | internal quotient @var{n} to the nearest integer instead of towards zero | |
322 | to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4}, | |
323 | which is @code{6.5} minus @code{6.9}. | |
324 | ||
325 | The absolute value of the result is less than or equal to half the | |
326 | absolute value of the @var{denominator}. The difference between | |
327 | @code{fmod (@var{numerator}, @var{denominator})} and @code{drem | |
328 | (@var{numerator}, @var{denominator})} is always either | |
329 | @var{denominator}, minus @var{denominator}, or zero. | |
330 | ||
331 | If @var{denominator} is zero, @code{drem} fails and sets @code{errno} to | |
332 | @code{EDOM}. | |
333 | @end deftypefun | |
334 | ||
335 | ||
336 | @node Integer Division | |
337 | @section Integer Division | |
338 | @cindex integer division functions | |
339 | ||
340 | This section describes functions for performing integer division. These | |
341 | functions are redundant in the GNU C library, since in GNU C the @samp{/} | |
342 | operator always rounds towards zero. But in other C implementations, | |
343 | @samp{/} may round differently with negative arguments. @code{div} and | |
344 | @code{ldiv} are useful because they specify how to round the quotient: | |
345 | towards zero. The remainder has the same sign as the numerator. | |
346 | ||
347 | These functions are specified to return a result @var{r} such that the value | |
348 | @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals | |
349 | @var{numerator}. | |
350 | ||
351 | @pindex stdlib.h | |
352 | To use these facilities, you should include the header file | |
353 | @file{stdlib.h} in your program. | |
354 | ||
355 | @comment stdlib.h | |
f65fd747 | 356 | @comment ISO |
28f540f4 RM |
357 | @deftp {Data Type} div_t |
358 | This is a structure type used to hold the result returned by the @code{div} | |
359 | function. It has the following members: | |
360 | ||
361 | @table @code | |
362 | @item int quot | |
363 | The quotient from the division. | |
364 | ||
365 | @item int rem | |
366 | The remainder from the division. | |
367 | @end table | |
368 | @end deftp | |
369 | ||
370 | @comment stdlib.h | |
f65fd747 | 371 | @comment ISO |
28f540f4 RM |
372 | @deftypefun div_t div (int @var{numerator}, int @var{denominator}) |
373 | This function @code{div} computes the quotient and remainder from | |
374 | the division of @var{numerator} by @var{denominator}, returning the | |
375 | result in a structure of type @code{div_t}. | |
376 | ||
377 | If the result cannot be represented (as in a division by zero), the | |
378 | behavior is undefined. | |
379 | ||
380 | Here is an example, albeit not a very useful one. | |
381 | ||
382 | @smallexample | |
383 | div_t result; | |
384 | result = div (20, -6); | |
385 | @end smallexample | |
386 | ||
387 | @noindent | |
388 | Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}. | |
389 | @end deftypefun | |
390 | ||
391 | @comment stdlib.h | |
f65fd747 | 392 | @comment ISO |
28f540f4 RM |
393 | @deftp {Data Type} ldiv_t |
394 | This is a structure type used to hold the result returned by the @code{ldiv} | |
395 | function. It has the following members: | |
396 | ||
397 | @table @code | |
398 | @item long int quot | |
399 | The quotient from the division. | |
400 | ||
401 | @item long int rem | |
402 | The remainder from the division. | |
403 | @end table | |
404 | ||
405 | (This is identical to @code{div_t} except that the components are of | |
406 | type @code{long int} rather than @code{int}.) | |
407 | @end deftp | |
408 | ||
409 | @comment stdlib.h | |
f65fd747 | 410 | @comment ISO |
28f540f4 RM |
411 | @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator}) |
412 | The @code{ldiv} function is similar to @code{div}, except that the | |
413 | arguments are of type @code{long int} and the result is returned as a | |
414 | structure of type @code{ldiv}. | |
415 | @end deftypefun | |
416 | ||
417 | ||
418 | @node Parsing of Numbers | |
419 | @section Parsing of Numbers | |
420 | @cindex parsing numbers (in formatted input) | |
421 | @cindex converting strings to numbers | |
422 | @cindex number syntax, parsing | |
423 | @cindex syntax, for reading numbers | |
424 | ||
425 | This section describes functions for ``reading'' integer and | |
426 | floating-point numbers from a string. It may be more convenient in some | |
427 | cases to use @code{sscanf} or one of the related functions; see | |
428 | @ref{Formatted Input}. But often you can make a program more robust by | |
429 | finding the tokens in the string by hand, then converting the numbers | |
430 | one by one. | |
431 | ||
432 | @menu | |
433 | * Parsing of Integers:: Functions for conversion of integer values. | |
434 | * Parsing of Floats:: Functions for conversion of floating-point | |
435 | values. | |
436 | @end menu | |
437 | ||
438 | @node Parsing of Integers | |
439 | @subsection Parsing of Integers | |
440 | ||
441 | @pindex stdlib.h | |
442 | These functions are declared in @file{stdlib.h}. | |
443 | ||
444 | @comment stdlib.h | |
f65fd747 | 445 | @comment ISO |
28f540f4 RM |
446 | @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base}) |
447 | The @code{strtol} (``string-to-long'') function converts the initial | |
448 | part of @var{string} to a signed integer, which is returned as a value | |
b8fe19fa | 449 | of type @code{long int}. |
28f540f4 RM |
450 | |
451 | This function attempts to decompose @var{string} as follows: | |
452 | ||
453 | @itemize @bullet | |
b8fe19fa | 454 | @item |
28f540f4 RM |
455 | A (possibly empty) sequence of whitespace characters. Which characters |
456 | are whitespace is determined by the @code{isspace} function | |
457 | (@pxref{Classification of Characters}). These are discarded. | |
458 | ||
b8fe19fa | 459 | @item |
28f540f4 RM |
460 | An optional plus or minus sign (@samp{+} or @samp{-}). |
461 | ||
b8fe19fa | 462 | @item |
28f540f4 RM |
463 | A nonempty sequence of digits in the radix specified by @var{base}. |
464 | ||
465 | If @var{base} is zero, decimal radix is assumed unless the series of | |
466 | digits begins with @samp{0} (specifying octal radix), or @samp{0x} or | |
467 | @samp{0X} (specifying hexadecimal radix); in other words, the same | |
468 | syntax used for integer constants in C. | |
469 | ||
470 | Otherwise @var{base} must have a value between @code{2} and @code{35}. | |
471 | If @var{base} is @code{16}, the digits may optionally be preceded by | |
2c6fe0bd UD |
472 | @samp{0x} or @samp{0X}. If base has no legal value the value returned |
473 | is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}. | |
28f540f4 | 474 | |
b8fe19fa | 475 | @item |
28f540f4 RM |
476 | Any remaining characters in the string. If @var{tailptr} is not a null |
477 | pointer, @code{strtol} stores a pointer to this tail in | |
478 | @code{*@var{tailptr}}. | |
479 | @end itemize | |
480 | ||
481 | If the string is empty, contains only whitespace, or does not contain an | |
482 | initial substring that has the expected syntax for an integer in the | |
483 | specified @var{base}, no conversion is performed. In this case, | |
484 | @code{strtol} returns a value of zero and the value stored in | |
485 | @code{*@var{tailptr}} is the value of @var{string}. | |
486 | ||
487 | In a locale other than the standard @code{"C"} locale, this function | |
488 | may recognize additional implementation-dependent syntax. | |
489 | ||
490 | If the string has valid syntax for an integer but the value is not | |
491 | representable because of overflow, @code{strtol} returns either | |
492 | @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as | |
493 | appropriate for the sign of the value. It also sets @code{errno} | |
494 | to @code{ERANGE} to indicate there was overflow. | |
495 | ||
2c6fe0bd UD |
496 | Because the value @code{0l} is a correct result for @code{strtol} the |
497 | user who is interested in handling errors should set the global variable | |
6d52618b UD |
498 | @code{errno} to @code{0} before calling this function, so that the program |
499 | can later test whether an error occurred. | |
2c6fe0bd | 500 | |
28f540f4 RM |
501 | There is an example at the end of this section. |
502 | @end deftypefun | |
503 | ||
504 | @comment stdlib.h | |
f65fd747 | 505 | @comment ISO |
28f540f4 RM |
506 | @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base}) |
507 | The @code{strtoul} (``string-to-unsigned-long'') function is like | |
b8fe19fa RM |
508 | @code{strtol} except it deals with unsigned numbers, and returns its |
509 | value with type @code{unsigned long int}. No @samp{+} or @samp{-} sign | |
510 | may appear before the number, but the syntax is otherwise the same as | |
511 | described above for @code{strtol}. The value returned in case of | |
512 | overflow is @code{ULONG_MAX} (@pxref{Range of Type}). | |
2c6fe0bd UD |
513 | |
514 | Like @code{strtol} this function sets @code{errno} and returns the value | |
515 | @code{0ul} in case the value for @var{base} is not in the legal range. | |
516 | For @code{strtoul} this can happen in another situation. In case the | |
517 | number to be converted is negative @code{strtoul} also sets @code{errno} | |
518 | to @code{EINVAL} and returns @code{0ul}. | |
519 | @end deftypefun | |
520 | ||
521 | @comment stdlib.h | |
522 | @comment BSD | |
523 | @deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base}) | |
524 | The @code{strtoq} (``string-to-quad-word'') function is like | |
525 | @code{strtol} except that is deals with extra long numbers and it | |
526 | returns its value with type @code{long long int}. | |
527 | ||
528 | If the string has valid syntax for an integer but the value is not | |
529 | representable because of overflow, @code{strtoq} returns either | |
530 | @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as | |
531 | appropriate for the sign of the value. It also sets @code{errno} to | |
532 | @code{ERANGE} to indicate there was overflow. | |
533 | @end deftypefun | |
534 | ||
535 | @comment stdlib.h | |
536 | @comment GNU | |
537 | @deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base}) | |
538 | @code{strtoll} is only an commonly used other name for the @code{strtoq} | |
539 | function. Everything said for @code{strtoq} applies to @code{strtoll} | |
540 | as well. | |
541 | @end deftypefun | |
542 | ||
543 | @comment stdlib.h | |
544 | @comment BSD | |
545 | @deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base}) | |
546 | The @code{strtouq} (``string-to-unsigned-quad-word'') function is like | |
547 | @code{strtoul} except that is deals with extra long numbers and it | |
548 | returns its value with type @code{unsigned long long int}. The value | |
549 | returned in case of overflow is @code{ULONG_LONG_MAX} (@pxref{Range of Type}). | |
550 | @end deftypefun | |
551 | ||
552 | @comment stdlib.h | |
553 | @comment GNU | |
554 | @deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base}) | |
555 | @code{strtoull} is only an commonly used other name for the @code{strtouq} | |
556 | function. Everything said for @code{strtouq} applies to @code{strtoull} | |
557 | as well. | |
28f540f4 RM |
558 | @end deftypefun |
559 | ||
560 | @comment stdlib.h | |
f65fd747 | 561 | @comment ISO |
28f540f4 RM |
562 | @deftypefun {long int} atol (const char *@var{string}) |
563 | This function is similar to the @code{strtol} function with a @var{base} | |
564 | argument of @code{10}, except that it need not detect overflow errors. | |
565 | The @code{atol} function is provided mostly for compatibility with | |
566 | existing code; using @code{strtol} is more robust. | |
567 | @end deftypefun | |
568 | ||
569 | @comment stdlib.h | |
f65fd747 | 570 | @comment ISO |
28f540f4 RM |
571 | @deftypefun int atoi (const char *@var{string}) |
572 | This function is like @code{atol}, except that it returns an @code{int} | |
573 | value rather than @code{long int}. The @code{atoi} function is also | |
574 | considered obsolete; use @code{strtol} instead. | |
575 | @end deftypefun | |
576 | ||
2c6fe0bd UD |
577 | The POSIX locales contain some information about how to format numbers |
578 | (@pxref{General Numeric}). This mainly deals with representing numbers | |
579 | for better readability for humans. The functions present so far in this | |
580 | section cannot handle numbers in this form. | |
581 | ||
582 | If this functionality is needed in a program one can use the functions | |
583 | from the @code{scanf} family which know about the flag @samp{'} for | |
584 | parsing numeric input (@pxref{Numeric Input Conversions}). Sometimes it | |
585 | is more desirable to have finer control. | |
586 | ||
587 | In these situation one could use the function | |
588 | @code{__strto@var{XXX}_internal}. @var{XXX} here stands for any of the | |
589 | above forms. All numeric conversion functions (including the functions | |
590 | to process floating-point numbers) have such a counterpart. The | |
26761c28 | 591 | difference to the normal form is the extra argument at the end of the |
2c6fe0bd | 592 | parameter list. If this value has an non-zero value the handling of |
26761c28 | 593 | number grouping is enabled. The advantage of using these functions is |
2c6fe0bd UD |
594 | that the @var{tailptr} parameters allow to determine which part of the |
595 | input is processed. The @code{scanf} functions don't provide this | |
596 | information. The drawback of using these functions is that they are not | |
597 | portable. They only exist in the GNU C library. | |
598 | ||
599 | ||
28f540f4 RM |
600 | Here is a function which parses a string as a sequence of integers and |
601 | returns the sum of them: | |
602 | ||
603 | @smallexample | |
604 | int | |
605 | sum_ints_from_string (char *string) | |
606 | @{ | |
607 | int sum = 0; | |
608 | ||
609 | while (1) @{ | |
610 | char *tail; | |
611 | int next; | |
612 | ||
613 | /* @r{Skip whitespace by hand, to detect the end.} */ | |
614 | while (isspace (*string)) string++; | |
615 | if (*string == 0) | |
616 | break; | |
617 | ||
618 | /* @r{There is more nonwhitespace,} */ | |
619 | /* @r{so it ought to be another number.} */ | |
620 | errno = 0; | |
621 | /* @r{Parse it.} */ | |
622 | next = strtol (string, &tail, 0); | |
623 | /* @r{Add it in, if not overflow.} */ | |
624 | if (errno) | |
625 | printf ("Overflow\n"); | |
626 | else | |
627 | sum += next; | |
628 | /* @r{Advance past it.} */ | |
629 | string = tail; | |
630 | @} | |
631 | ||
632 | return sum; | |
633 | @} | |
634 | @end smallexample | |
635 | ||
636 | @node Parsing of Floats | |
637 | @subsection Parsing of Floats | |
638 | ||
639 | @pindex stdlib.h | |
640 | These functions are declared in @file{stdlib.h}. | |
641 | ||
642 | @comment stdlib.h | |
f65fd747 | 643 | @comment ISO |
28f540f4 RM |
644 | @deftypefun double strtod (const char *@var{string}, char **@var{tailptr}) |
645 | The @code{strtod} (``string-to-double'') function converts the initial | |
646 | part of @var{string} to a floating-point number, which is returned as a | |
b8fe19fa | 647 | value of type @code{double}. |
28f540f4 RM |
648 | |
649 | This function attempts to decompose @var{string} as follows: | |
650 | ||
651 | @itemize @bullet | |
b8fe19fa | 652 | @item |
28f540f4 RM |
653 | A (possibly empty) sequence of whitespace characters. Which characters |
654 | are whitespace is determined by the @code{isspace} function | |
655 | (@pxref{Classification of Characters}). These are discarded. | |
656 | ||
657 | @item | |
658 | An optional plus or minus sign (@samp{+} or @samp{-}). | |
659 | ||
660 | @item | |
661 | A nonempty sequence of digits optionally containing a decimal-point | |
662 | character---normally @samp{.}, but it depends on the locale | |
663 | (@pxref{Numeric Formatting}). | |
664 | ||
665 | @item | |
666 | An optional exponent part, consisting of a character @samp{e} or | |
667 | @samp{E}, an optional sign, and a sequence of digits. | |
668 | ||
669 | @item | |
670 | Any remaining characters in the string. If @var{tailptr} is not a null | |
671 | pointer, a pointer to this tail of the string is stored in | |
672 | @code{*@var{tailptr}}. | |
673 | @end itemize | |
674 | ||
675 | If the string is empty, contains only whitespace, or does not contain an | |
676 | initial substring that has the expected syntax for a floating-point | |
677 | number, no conversion is performed. In this case, @code{strtod} returns | |
678 | a value of zero and the value returned in @code{*@var{tailptr}} is the | |
679 | value of @var{string}. | |
680 | ||
26761c28 | 681 | In a locale other than the standard @code{"C"} or @code{"POSIX"} locales, |
2c6fe0bd | 682 | this function may recognize additional locale-dependent syntax. |
28f540f4 RM |
683 | |
684 | If the string has valid syntax for a floating-point number but the value | |
685 | is not representable because of overflow, @code{strtod} returns either | |
686 | positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on | |
687 | the sign of the value. Similarly, if the value is not representable | |
688 | because of underflow, @code{strtod} returns zero. It also sets @code{errno} | |
689 | to @code{ERANGE} if there was overflow or underflow. | |
2c6fe0bd UD |
690 | |
691 | Since the value zero which is returned in the error case is also a valid | |
26761c28 | 692 | result the user should set the global variable @code{errno} to zero |
2c6fe0bd UD |
693 | before calling this function. So one can test for failures after the |
694 | call since all failures set @code{errno} to a non-zero value. | |
28f540f4 RM |
695 | @end deftypefun |
696 | ||
2c6fe0bd UD |
697 | @comment stdlib.h |
698 | @comment GNU | |
699 | @deftypefun float strtof (const char *@var{string}, char **@var{tailptr}) | |
700 | This function is similar to the @code{strtod} function but it returns a | |
701 | @code{float} value instead of a @code{double} value. If the precision | |
6d52618b | 702 | of a @code{float} value is sufficient this function should be used since |
2c6fe0bd UD |
703 | it is much faster than @code{strtod} on some architectures. The reasons |
704 | are obvious: @w{IEEE 754} defines @code{float} to have a mantissa of 23 | |
705 | bits while @code{double} has 53 bits and every additional bit of | |
706 | precision can require additional computation. | |
707 | ||
708 | If the string has valid syntax for a floating-point number but the value | |
709 | is not representable because of overflow, @code{strtof} returns either | |
710 | positive or negative @code{HUGE_VALf} (@pxref{Mathematics}), depending on | |
711 | the sign of the value. | |
712 | ||
713 | This function is a GNU extension. | |
714 | @end deftypefun | |
715 | ||
716 | @comment stdlib.h | |
717 | @comment GNU | |
718 | @deftypefun {long double} strtold (const char *@var{string}, char **@var{tailptr}) | |
719 | This function is similar to the @code{strtod} function but it returns a | |
720 | @code{long double} value instead of a @code{double} value. It should be | |
6d52618b | 721 | used when high precision is needed. On systems which define a @code{long |
2c6fe0bd | 722 | double} type (i.e., on which it is not the same as @code{double}) |
6d52618b | 723 | running this function might take significantly more time since more bits |
2c6fe0bd UD |
724 | of precision are required. |
725 | ||
726 | If the string has valid syntax for a floating-point number but the value | |
727 | is not representable because of overflow, @code{strtold} returns either | |
728 | positive or negative @code{HUGE_VALl} (@pxref{Mathematics}), depending on | |
729 | the sign of the value. | |
730 | ||
731 | This function is a GNU extension. | |
732 | @end deftypefun | |
733 | ||
734 | As for the integer parsing functions there are additional functions | |
735 | which will handle numbers represented using the grouping scheme of the | |
736 | current locale (@pxref{Parsing of Integers}). | |
737 | ||
28f540f4 | 738 | @comment stdlib.h |
f65fd747 | 739 | @comment ISO |
28f540f4 RM |
740 | @deftypefun double atof (const char *@var{string}) |
741 | This function is similar to the @code{strtod} function, except that it | |
742 | need not detect overflow and underflow errors. The @code{atof} function | |
743 | is provided mostly for compatibility with existing code; using | |
744 | @code{strtod} is more robust. | |
745 | @end deftypefun |