wstod(3c) - osol9

1wcstod(3C)               Standard C Library Functions               wcstod(3C)
2
3
4

NAME

6       wcstod,  wcstof,  wcstold, wstod, watof - convert wide character string
7       to floating-point number
8

SYNOPSIS

10       #include <wchar.h>
11
12       double wcstod(const wchar_t *restrict nptr,
13            wchar_t **restrict endptr);
14
15
16       float wcstof(const wchar_t *restrict nptr,
17            wchar_t **restrict endptr);
18
19
20       long double wcstold(const wchar_t *restrict nptr,
21            wchar_t **restrict endptr);
22
23
24       double wstod(const wchar_t *nptr, wchar_t **endptr);
25
26
27       double watof(wchar_t *nptr);
28
29

DESCRIPTION

31       The wcstod(), wcstof(), and wcstold()  functions  convert  the  initial
32       portion  of  the  wide-character  string  pointed to by nptr to double,
33       float, and long double representation, respectively. They first  decom‐
34       pose the input wide-character string into three parts:
35
36           1.     An  initial,  possibly  empty, sequence of white-space wide-
37                  character codes (as specified by iswspace(3C))
38
39           2.     A subject sequence interpreted as a floating-point  constant
40                  or representing infinity or NaN
41
42           3.     A  final  wide-character  string of one or more unrecognized
43                  wide-character codes, including the terminating  null  wide-
44                  character code of the input wide-character string.
45
46
47       Then  they  attempt to convert the subject sequence to a floating-point
48       number, and return the result.
49
50
51       The expected form of the subject sequence is an optional plus or  minus
52       sign, then one of the following:
53
54           o      A non-empty sequence of decimal digits optionally containing
55                  a radix character, then an optional exponent part
56
57           o      A 0x or 0X, then a non-empty sequence of hexadecimal  digits
58                  optionally  containing  a  radix character, then an optional
59                  binary exponent part
60
61           o      One of INF or INFINITY, or any other wide string  equivalent
62                  except for case
63
64           o      One  of NAN or NAN(n-wchar-sequence(opt)), or any other wide
65                  string ignoring case in the NAN part, where:
66
67                    n-wchar-sequence:
68                        digit
69                        nondigit
70                        n-wchar-sequence digit
71                        n-wchar-sequence nondigit
72
73
74
75       In  default  mode  for  wcstod(),  only  decimal,   INF/INFINITY,   and
76       NAN/NAN(n-char-sequence) forms are recognized. In C99/SUSv3 mode, hexa‐
77       decimal strings are also recognized.
78
79
80       In default mode for wcstod(), the n-char-sequence  in  the  NAN(n-char-
81       equence)  form can contain any character except ')' (right parenthesis)
82       or '\0' (null).  In C99/SUSv3 mode,  the  n-char-sequence  can  contain
83       only upper and lower case letters, digits, and '_' (underscore).
84
85
86       The  wcstof() and wcstold() functions always function in C99/SUSv3-con‐
87       formant mode.
88
89
90       The subject sequence is defined as the longest initial  subsequence  of
91       the  input  wide  string,  starting with the first non-white-space wide
92       character, that is of the expected form. The subject sequence  contains
93       no  wide  characters  if  the  input wide string is not of the expected
94       form.
95
96
97       If the subject sequence has the expected form for a floating-point num‐
98       ber,  the  sequence of wide characters starting with the first digit or
99       the radix character (whichever occurs first) is interpreted as a float‐
100       ing  constant according to the rules of the C language, except that the
101       radix character is used in place of a period, and that  if  neither  an
102       exponent part nor a radix character appears in a decimal floating-point
103       number, or if a binary exponent part does not appear in  a  hexadecimal
104       floating-point  number,  an  exponent part of the appropriate type with
105       value zero is assumed to follow the last digit in the  string.  If  the
106       subject  sequence begins with a minus sign, the sequence is interpreted
107       as negated. A wide-character sequence INF or INFINITY is interpreted as
108       an   infinity.   A   wide-character   sequence   NAN   or  NAN(n-wchar-
109       sequence(opt)) is interpreted as a quiet NaN. A pointer  to  the  final
110       wide string is stored in the object pointed to by endptr, provided that
111       endptr is not a null pointer.
112
113
114       If the subject sequence has either the decimal or hexadecimal form, the
115       value  resulting  from the conversion is rounded correctly according to
116       the prevailing floating point rounding direction mode.  The  conversion
117       also  raises  floating point inexact, underflow, or overflow exceptions
118       as appropriate.
119
120
121       The radix character  is  defined  in  the  program's  locale  (category
122       LC_NUMERIC).  In the POSIX locale, or in a locale where the radix char‐
123       acter is not defined, the radix character defaults to a period ('.').
124
125
126       If the subject sequence is empty or does not have the expected form, no
127       conversion  is  performed;  the  value of  nptr is stored in the object
128       pointed to by endptr, provided that  endptr is not a null pointer.
129
130
131       The wcstod() function does not change the setting of errno if  success‐
132       ful.
133
134
135       The wstod() function is identical to wcstod().
136
137
138       The watof(str) function is equivalent to wstod(nptr, (wchar_t **)NULL).
139

RETURN VALUES

141       Upon successful completion, these functions return the converted value.
142       If no conversion could be performed, 0 is returned.
143
144
145       If the correct value is outside  the  range  of  representable  values,
146       ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned (according to the sign
147       of the value), a floating point overflow exception is raised, and errno
148       is set to ERANGE.
149
150
151       If  the  correct  value would cause an underflow, the correctly rounded
152       result (which may be normal, subnormal, or zero) is returned, a  float‐
153       ing point underflow exception is raised, and errno is set to ERANGE.
154

ERRORS

156       The wcstod() and wstod() functions will fail if:
157
158       ERANGE    The value to be returned would cause overflow or underflow.
159
160
161
162       The wcstod() and wcstod() functions may fail if:
163
164       EINVAL    No conversion could be performed.
165
166

USAGE

168       Because  0  is returned on error and is also a valid return on success,
169       an application wishing to check for error situations should  set  errno
170       to  0 call wcstod(), wcstof(), wcstold(), or wstod(), then check  errno
171       and if it is non-zero, assume an error has occurred.
172

ATTRIBUTES

174       See attributes(5) for descriptions of the following attributes:
175
176
177
178
179       ┌─────────────────────────────┬─────────────────────────────┐
180       │ATTRIBUTE TYPE               │ATTRIBUTE VALUE              │
181       ├─────────────────────────────┼─────────────────────────────┤
182       │Interface Stability          │wcstod(),   wcstof(),   and  │
183       │                             │wcstold() are Standard.      │
184       ├─────────────────────────────┼─────────────────────────────┤
185       │MT-Level                     │MT-Safe                      │
186       └─────────────────────────────┴─────────────────────────────┘
187