Standard C Library Functions wcstod(3C)
NAME
wcstod, wcstof, wcstold, wstod, watof - convert wide charac-
ter string to floating-point number
SYNOPSIS
#include
double wcstod(const wchart *restrict nptr,
wchart **restrict endptr);
float wcstof(const wchart *restrict nptr,
wchart **restrict endptr);
long double wcstold(const wchart *restrict nptr,
wchart **restrict endptr);
double wstod(const wchart *nptr, wchart **endptr);
double watof(wchart *nptr);
DESCRIPTION
The wcstod(), wcstof(), and wcstold() functions convert the
initial portion of the wide-character string pointed to by
nptr to double, float, and long double representation,
respectively. They first decompose the input wide-character
string into three parts:
1. An initial, possibly empty, sequence of white-space
wide-character codes (as specified by iswspace(3C))
2. A subject sequence interpreted as a floating-point
constant or representing infinity or NaN
3. A final wide-character string of one or more
unrecognized wide-character codes, including the
terminating null wide-character code of the input
wide-character string.
Then they attempt to convert the subject sequence to a
floating-point number, and return the result.
The expected form of the subject sequence is an optional
plus or minus sign, then one of the following:
o A non-empty sequence of decimal digits optionally
SunOS 5.11 Last change: 31 Mar 2003 1
Standard C Library Functions wcstod(3C)
containing a radix character, then an optional
exponent part
o A 0x or 0X, then a non-empty sequence of hexade-
cimal digits optionally containing a radix charac-
ter, then an optional binary exponent part
o One of INF or INFINITY, or any other wide string
equivalent except for case
o One of NAN or NAN(n-wchar-sequence(opt)), or any
other wide string ignoring case in the NAN part,
where:
n-wchar-sequence:
digit
nondigit
n-wchar-sequence digit
n-wchar-sequence nondigit
In default mode for wcstod(), only decimal, INF/INFINITY,
and NAN/NAN(n-char-sequence) forms are recognized. In
C99/SUSv3 mode, hexadecimal strings are also recognized.
In default mode for wcstod(), the n-char-sequence in the
NAN(n-char-equence) form can contain any character except
')' (right parenthesis) or '\0' (null). In C99/SUSv3 mode,
the n-char-sequence can contain only upper and lower case
letters, digits, and '' (underscore).
The wcstof() and wcstold() functions always function in
C99/SUSv3-conformant mode.
The subject sequence is defined as the longest initial
subsequence of the input wide string, starting with the
first non-white-space wide character, that is of the
expected form. The subject sequence contains no wide charac-
ters if the input wide string is not of the expected form.
If the subject sequence has the expected form for a
floating-point number, the sequence of wide characters
starting with the first digit or the radix character (which-
ever occurs first) is interpreted as a floating constant
according to the rules of the C language, except that the
radix character is used in place of a period, and that if
neither an exponent part nor a radix character appears in a
SunOS 5.11 Last change: 31 Mar 2003 2
Standard C Library Functions wcstod(3C)
decimal floating-point number, or if a binary exponent part
does not appear in a hexadecimal floating-point number, an
exponent part of the appropriate type with value zero is
assumed to follow the last digit in the string. If the sub-
ject sequence begins with a minus sign, the sequence is
interpreted as negated. A wide-character sequence INF or
INFINITY is interpreted as an infinity. A wide-character
sequence NAN or NAN(n-wchar-sequence(opt)) is interpreted as
a quiet NaN. A pointer to the final wide string is stored in
the object pointed to by endptr, provided that endptr is not
a null pointer.
If the subject sequence has either the decimal or hexade-
cimal form, the value resulting from the conversion is
rounded correctly according to the prevailing floating point
rounding direction mode. The conversion also raises floating
point inexact, underflow, or overflow exceptions as
appropriate.
The radix character is defined in the program's locale
(category LCNUMERIC). In the POSIX locale, or in a locale
where the radix character is not defined, the radix charac-
ter defaults to a period ('.').
If the subject sequence is empty or does not have the
expected form, no conversion is performed; the value of
nptr is stored in the object pointed to by endptr, provided
that endptr is not a null pointer.
The wcstod() function does not change the setting of errno
if successful.
The wstod() function is identical to wcstod().
The watof(str) function is equivalent to wstod(nptr,
(wchart **)NUL).
RETURN VALUES
Upon successful completion, these functions return the con-
verted value. If no conversion could be performed, 0 is
returned.
If the correct value is outside the range of representable
values, ]HUGEVAL, ]HUGEVALF, or ]HUGEVAL is returned
(according to the sign of the value), a floating point
SunOS 5.11 Last change: 31 Mar 2003 3
Standard C Library Functions wcstod(3C)
overflow exception is raised, and errno is set to ERANGE.
If the correct value would cause an underflow, the correctly
rounded result (which may be normal, subnormal, or zero) is
returned, a floating point underflow exception is raised,
and errno is set to ERANGE.
ERORS
The wcstod() and wstod() functions will fail if:
ERANGE The value to be returned would cause overflow or
underflow.
The wcstod() and wcstod() functions may fail if:
EINVAL No conversion could be performed.
USAGE
Because 0 is returned on error and is also a valid return on
success, an application wishing to check for error situa-
tions should set errno to 0 call wcstod(), wcstof(),
wcstold(), or wstod(), then check errno and if it is non-
zero, assume an error has occurred.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability wcstod(), wcstof(), and
wcstold() are Standard.
MT-Level MT-Safe
SEE ALSO
iswspace(3C), localeconv(3C), scanf(3C), setlocale(3C),
wcstol(3C), attributes(5), standards(5)
SunOS 5.11 Last change: 31 Mar 2003 4
|
