wcstoul() – wcstoull() — Convert Wide Character String to Unsigned Long and Unsigned Long Long Integer
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()
function 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 function). 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()
function
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()
function
returns a value of ULONG_LONG_MAX.
Example
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
- strtod() - strtof() - strtold() — Convert Character String to Double, Float, and Long Double
- strtod32() - strtod64() - strtod128() — Convert Character String to Decimal Floating-Point
- strtol() – strtoll() — Convert Character String to Long and Long Long Integer
- wcstod() - wcstof() - wcstold() — Convert Wide-Character String to Double, Float, and Long Double
- wcstod32() - wcstod64() - wcstod128() — Convert Wide-Character String to Decimal Floating-Point
- wcstol() – wcstoll() — Convert Wide Character String to Long and Long Long Integer
- <wchar.h>