Converts a wide-character string to a long integer representation.
Standard C Library (libc.a)
The wcstol subroutine converts a wide-character string to a long integer representation. The wcstoll subroutine converts a wide-character string to a long long integer representation.
If possible, the subject is then converted to an integer, and the result is returned.
The Base parameter can take the following values: 0 through 9, or a (or A) through z (or Z). There are potentially 36 values for the base. If the base value is 0, the expected form of the subject string is that of a decimal, octal, or hexadecimal constant, any of which can be preceded by a + (plus sign) or - (minus sign). A decimal constant starts with a non zero digit, and is composed of a sequence of decimal digits. An octal constant consists of the prefix 0 optionally followed by a sequence of the digits 0 to 7. A hexadecimal constant is defined as the prefix 0x (or 0X) followed by a sequence of decimal digits and the letters a (or A) to f (or F) with values ranging from 10 (for a or A) to 15 (for f or F).
If the base value is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer in the radix specified by the Base parameter, optionally preceded by a + or -, but not including an integer suffix. The letters a (or A) through z (or Z) are ascribed the values of 10 to 35. Only letters whose values are less than that of the base are permitted. If the value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters or digits, following the sign, if present.
The wide-character string is parsed to skip the initial space characters (as determined by the iswspace subroutine). Any non-space character signifies the start of a subject string that may form an integer in the radix specified by the Base parameter. The subject sequence is defined to be the longest initial substring that is a long integer of the expected form. Any character not satisfying this form begins the final portion of the wide-character string pointed to by the Endptr parameter on return from the call to the wcstol or wcstoll subroutine.
| Item | Description |
|---|---|
| Nptr | Contains a pointer to the wide-character string to be converted to a long integer number. |
| Endptr | Contains a pointer to the position in the Nptr parameter string where a wide-character is found that is not a valid character. |
| Base | Specifies the radix in which the characters are interpreted. |
The wcstol and wcstoll subroutines return the converted value of the long or long long integer if the expected form is found. If no conversion could be performed, a value of 0 is returned. If the converted value is outside the range of representable values, LONG_MAX or LONG_MIN is returned for the wcstol subroutine and LLONG_MAX or LLONG_MIN is returned for the wcstoll subroutine (according to the sign of the value). The value of errno is set to ERANGE. If the base value specified by the Base parameter is not supported, EINVAL is returned.
If the subject sequence has the expected form, it is interpreted as an integer constant in the appropriate base. A pointer to the final string is stored in the Endptr parameter if that parameter is not a null pointer.
If the subject sequence is empty or does not have a valid form, no conversion is done. The value of the Nptr parameter is stored in the Endptr parameter if that parameter is not a null pointer.
Since 0, LONG_MIN, and LONG_MAX (for wcstol) and LLONG_MIN, and LLONG_MAX (for wcstoll) are returned in the event of an error and are also valid returns if the wcstol or wcstoll subroutine is successful, applications should set the errno global variable to 0 before calling either subroutine, and check errno after return. If the errno global value has changed, an error occurred.
To convert a wide-character string to a signed long integer, use the following code:
#include <stdlib.h>
#include <locale.h>
#include <errno.h>main()
{
wchar_t *WCString, *endptr;
long int retval;
(void)setlocale(LC_ALL, "");
/**Set errno to 0 so a failure for wcstol can be
**detected */
errno=0;
/*
**Let WCString point to a wide character null terminated
** string containing a signed long integer value
**
*/retval = wcstol ( WCString &endptr, 0 );
/* Check errno, if it is non-zero, wcstol failed */
if (errno != 0) {
/*Error handling*/
}
else if (&WCString == endptr) {
/* No conversion could be performed */
/* Handle this case accordingly. */
}
/* retval contains long integer */
}