wcstod, wcstof, or wcstold Subroutine

Purpose

Converts a wide character string to a double-precision number.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>
#include <wchar.h>
double wcstod ( nptr,  endptr)
const wchar_t *nptr;
wchar_t **endptr;

float wcstof (nptr, endptr)
const wchar_t *restrict nptr;
wchar_t **restrict endptr;

long double wcstold (nptr, endptr)
const wchar_t *restrict format;
wchar_t **restrict nptr;

Description

The wcstod, wcstof, and wcstold subroutines convert the initial portion of the wide-character string pointed to by nptr to double, float and long double representation, respectively. First, they decompose the input wide-character string into three parts:
  • An initial, possibly empty, sequence of white-space wide-character codes.
  • A subject sequence interpreted as a floating-point constant or representing infinity or NaN.
  • 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 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, and one of the following:
  • A non-empty sequence of decimal digits optionally containing a radix character, and an optional exponent part.
  • A 0x or 0X, and a non-empty sequence of hexadecimal digits optionally containing a radix character, and an optional binary exponent part.
  • One of INF or INFINITY, or any other wide string equivalent except for case.
  • 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

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 characters 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 (whichever occurs first) are 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. If neither an exponent part or a radix character appears in a 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 subject sequence begins with a minus sign, the sequence is interpreted as negated. A wide-character sequence INF or INFINITY is interpreted as an infinity, if representable in the return type, or else as if it were a floating constant that is too large for the range of the return type. A wide-character sequence NAN or NAN(n-wchar-sequence opt ) is interpreted as a quiet NaN, if supported in the return type, or else as if it were a subject sequence part that does not have the expected form. The meaning of the n-wchar sequences is implementation-defined. 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 the hexadecimal form and FLT_RADIX is a power of 2, the conversion will be rounded in an implementation-defined manner.

The radix character is as defined in the program's locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the radix character defaults to a period.

In other than the C or POSIX locales, other implementation-defined subject sequences may be accepted.

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, wcstof, and wcstold subroutines do not change the setting of the errno global variable if successful.

Since 0 is returned on error and is also a valid return on success, an application wishing to check for error situations should set errno to 0, call wcstod, wcstof, or wcstold, and check errno.

Parameters

Item Description
nptr Contains a pointer to the wide character string to be converted to a double-precision value.
endptr Contains a pointer to the position in the string specified by the nptr parameter where a wide character is found that is not a valid character for the purpose of this conversion.

Return Values

Upon successful completion, the wcstod, wcstof, and wcstold subroutines return the converted value. If no conversion could be performed, 0 is returned and the errno global variable may be set to EINVAL.

If the correct value is outside the range of representable values, plus or minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the sign of the value), and errno is set to ERANGE.

If the correct value would cause underflow, a value whose magnitude is no greater than the smallest normalized positive number in the return type is returned and errno set to ERANGE.