Format (wcstoul())
#include <wchar.h>
unsigned long int wcstoul(const wchar_t *nptr, wchar_t **endptr, int base);Format (wcstoull())
#include <wchar.h>
unsigned long long int wcstoull(const wchar_t *nptr, wchar_t **endptr, int base);Language Level: ANSI
Threadsafe: Yes.
Locale Sensitive: The behavior of these functions might be affected by the LC_CTYPE category of the current locale if LOCALETYPE(*LOCALE) is specified on the compilation command. The behavior of these functions might also be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. These functions are not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Wide Character Function: See Wide Characters for more information.
Description
The wcstoul() function converts the initial portion of the wide-character string pointed to by nptr to an unsigned long integer value. The nptr parameter points to a sequence of wide characters that can be interpreted as a numerical value of type unsigned long int. The wcstoul() function stops reading the string at the first wide character that it cannot recognize as part of a number. This character can be the wchar_t null character at the end of the string. The ending character can also be the first numeric character greater than or equal to the base.
The wcstoull() subroutine converts a wide-character string to an unsigned long long integer. 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 unsigned long long int in the radix specified by the base parameter. The subject sequence is defined to be the longest initial substring that is an unsigned long long int of the expected form.
If the value of the endptr parameter is not null, then a pointer to the character that ended the scan is stored in endptr. If an unsigned long long integer cannot be formed, the value of the endptr parameter is set to that of the nptr parameter.
If the base parameter is a value between 2 and 36, the subject sequence's expected form is a sequence of letters and digits representing an unsigned long long integer whose radix is specified by the base parameter. This sequence optionally is preceded by a positive (+) or negative (-) sign. Letters from a (or A) to z (or Z) inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less than that of the base parameter are permitted. If the base parameter has a value of 16, the characters 0x or 0X optionally precede the sequence of letters and digits, following the positive (+) or negative (-) sign, if present.
If the value of the base parameter is 0, the string determines the base. Therefore, after an optional leading sign, a leading 0 indicates octal conversion, and a leading 0x or 0X indicates hexadecimal conversion.
The value of errno may be set to EINVAL (endptr is null, no numbers are found, or base is invalid), or ERANGE (converted value is outside the range).
Return Value
The wcstoul() function returns the converted unsigned long integer value. If no conversion could be performed, the wcstoul() function returns 0. If the correct value is outside the range of representable values, the wcstoul() function returns ULONG_MAX and sets errno to ERANGE. If the string nptr points to is empty or does not have the expected form, no conversion is performed, and the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Upon successful completion, the wcstoull() subroutine returns the converted value. If no conversion could be performed, 0 is returned, and the errno global variable is set to indicate the error. If the correct value is outside the range of representable values, wcstoull() subroutine returns a value of ULONG_LONG_MAX.
Example that uses wcstoul()
This example uses the wcstoul() function to convert the string wcs to an unsigned long integer value.
#include <stdio.h>
#include <wchar.h>
#define BASE 2
int main(void)
{
wchar_t *wcs = L"1000e13 camels";
wchar_t *endptr;
unsigned long int answer;
answer = wcstoul(wcs, &endptr, BASE);
printf("The input wide string used: `%ls`\n"
"The unsigned long int produced: %lu\n"
"The substring of the input wide string that was not"
" converted to unsigned long: `%ls`\n", wcs, answer, endptr);
return 0;
/*********************************************************************
The output should be similar to:
The input wide string used: 1000e13 camels
The unsigned long int produced: 8
The substring of the input wide string that was not converted to
unsigned long: e13 camels
*********************************************************************/
}Related Information