wcstod(S)

wcstod, wcstol, wcstoul -- convert wide character string to number

Syntax

cc . . . -lc

#include <wchar.h>

double            wcstod (const wchar_t *nptr, wchar_t **endptr);
long int          wcstol (const wchar_t *nptr, wchar_t **endptr, int base);
unsigned long int wcstoul(const wchar_t *nptr, wchar_t **endptr, int base);

Description

All these routines convert a wide character string to a number which the string represents numerically. nptr points to the start of the wide character string to be converted. If endptr is not wchar_t **)NULL when these routines are called, it will, on return, point to the trailing wide character substring in nptr that is not part of the number, or point to nptr if no conversion is possible. For wcstol(S) and wcstoul(S), the value of base determines the radix of the integer represented by the string.

Ignored in the conversion are leading white-space wide-character codes (if any) in the string and the trailing substring of the string not forming part of any number (including the terminating null wide-character code). The portion of the wide character string between these possible leading white-spaces and the trailing substring is defined as the subject sequence. Only the subject sequence of the string is actually converted. The converted result is then returned.

No conversion is performed if the subject sequence is empty or does not have the expected form.

The subject sequence is empty if the input wide character string is empty or contains only white-space wide-character codes. The subject sequence is also empty if the first non-white-space character in the string is not a sign, not a permissible letter or not a permissible digit when the string represents an integer, or if the first non-white-space character is not a sign, not a digit or not a radix when the string represents a floating point number.

The expected forms of a subject sequence are shown in the table below, for some typical values of base and expressed as regular expressions. They are also described in detail for each routine following the table.

Routine Expected Form

Comments

wcstod( ) [-+][0-9]+(.[0-9])?([eE][+-]?[0-9]+)?

floating number

[-+].[0-9]+([eE][+-]?[0-9]+)? wcstol( )
and
wcstoul( )

base 0 [-+]0[xX][0-9a-fA-F]+ hex number

[-+]0[0-7] octal number

[-+][1-9][0-9] decimal number

base 10 [-+][1-9][0-9] decimal number

base 16 [-+](0[xX])?[0-9a-fA-F]+ hex number

base 36 [-+][0-9a-zA-Z]+

Routine	Expected Form
Comments
wcstod( )	[-+][0-9]+(.[0-9])?([eE][+-]?[0-9]+)?
floating number
	[-+].[0-9]+([eE][+-]?[0-9]+)?	wcstol( ) and wcstoul( )
base 0	[-+]0[xX][0-9a-fA-F]+	hex number
		[-+]0[0-7]	octal number
		[-+][1-9][0-9]	decimal number
	base 10	[-+][1-9][0-9]	decimal number
	base 16	[-+](0[xX])?[0-9a-fA-F]+	hex number
	base 36	[-+][0-9a-zA-Z]+

For floating point numbers, i.e., for wcstod(S), the expected form of subject sequence starts with an optional + or - sign, followed by a string of digits optionally containing a radix, then ended with an optional exponent part. The exponent part starts with the letter e or E, followed by an optional sign, and then ended with one or more digits.

The program's locale (category LC_NUMERIC) determines the radix used. The default of the radix is a period (.); it is used in the POSIX locale or in a locale where the radix is not defined.

If the subject sequence has the expected form, this sequence (excluding the optional leading sign) is interpreted as a floating point constant as defined in the C language, except that the radix may not be a period here. A radix is assumed to follow the last digit when the sequence does not end with either an exponent part or a radix.

For integers, i.e., for wcstol( ) and wcstoul( ), the expected form of subject sequence has slightly different forms depending on whether the value of base is zero or between 2 and 36.

When the value of base is zero, the expected form of subject sequence starts with an optional + or - sign, and can end with any one of a decimal constant, a octal constant, or a hexadecimal constant. A decimal constant starts with a non-zero digit, and is a sequence of digits. An octal constant starts with the prefix 0 followed by an optional sequence of the digits in the range of 0 to 7 inclusive. A hexadecimal constants starts with either the prefix 0x or 0X. After the prefix is a non-empty sequence of the digits and letters. The letters are in the range from a (or A) to f (or F), and are assigned numerical values 10 to 15 respectively.

When the value of base is between 2 and 36, the expected form of subject sequence starts with an optional + or - sign, and ends with a sequence of letters and digits representing an integer. The radix of the integer is determined by base. The integer suffix, such as ``L'' or ``U'', is not included as part of the subject sequence. The letters from a (or A) to z (or Z) inclusive are assigned values 10 to 35. If a letter's value is greater than base, that letter cannot be used in the subject sequence. For base 16, the optional prefix 0x or 0X may be specified, between the optional sign and the sequence of letters and digits representing the integer.

For base zero, the sequence starting at the first digit is interpreted as an integer constant, if the subject sequence has the expected form. If the value of base is between 2 and 36 and the subject sequence has the expected form, this sequence is interpreted as an integer constant represented in the radix of base, with each letter having a value as given above. A minus sign, if present, is then added to the converted number.

A minus sign is also legal for wcstoul( ), and the value of the negative constant is converted to that of an unsigned long.

Return values

Upon successful completion, these routines return the converted value.

If no conversion is possible, zero is returned; wcstod( ) also sets errno to [EINVAL].

If the correct converted value would cause overflow, errno is set to [ERANGE], and, according to the sign of the value, wcstod( ) returns ±HUGE_VAL instead, wcstol( ) returns LONG_MAX or LONG_MIN instead, and wcstoul( ) returns ULONG_MAX instead.

If the correct value returned by wcstod( ) would cause underflow, zero is returned instead and errno is also set to [ERANGE].

Diagnostics

These routines will fail if:

[ERANGE]: The converted value is outside the representable range.

In addition, wcstol( ) and wcstoul( ) will fail if:

[EINVAL]: The value of base is not supported.

wcstod( ) will fail if:

[EINVAL]: No conversion is possible.

Notes

The macros LONG_MAX, LONG_MIN and ULONG_MAX are defined in <limits.h>, and the macro HUGE_VAL is defined in <math.h>

LONG_MAX and LONG_MIN for long int, ULONG_MAX for unsigned long int, and zero for both long int types and for double type, can be returned both on error and as a valid return on success, and therefore should not be used to check for error situations. To check for error, set errno to zero prior to the call. If errno is non-zero on return, assume that there is an error during the call.

Warning

Unlike wcstod( ) and wcstol( ), the number returned by wcstoul( ) is always non-negative. The use of a return value of wcstoul( ) without an errno check could be a source of more severe problems than a simple loss of precision, if any out-of-range numbers can also be negative.

Standards conformance

wcstod( ), wcstol( ), and wcstoul( ) are conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992.