wcstol() – wcstoll() — Convert Wide Character String to Long and Long Long Integer
Format (wcstol()
)
#include <wchar.h>
long int wcstol(const wchar_t *nptr, wchar_t **endptr, int base);
Format (wcstoll()
)
#include <wchar.h>
long long int wcstoll(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 wcstol()
function
converts the initial portion of the wide-character string pointed
to by nptr to a long integer value. The nptr parameter
points to a sequence of wide characters that can be interpreted as
a numerical value of type long int. The wcstol()
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 wcstoll()
function converts a wide-character
string to a 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 a long long int in the radix specified by the base parameter.
The subject sequence is defined to be the longest initial substring
that is a 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 a 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 a 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.
Return Value
The wcstol()
function
returns the converted long integer value. If no conversion could be
performed, the wcstol()
function
returns 0. If the correct value is outside the range of representable
values, the wcstol()
function
returns LONG_MAX or LONG_MIN (according to the sign of the value),
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 wcstoll()
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,
the wcstoll()
function returns a value of LONG_LONG_MAX
or LONG_LONG_MIN.
The value of errno
may be set to ERANGE (range
error), or EINVAL (invalid argument).
Example
wcstol()
function
to convert the wide-character string wcs to a long integer
value. #include <stdio.h>
#include <wchar.h>
int main(void)
{
wchar_t *wcs = L"10110134932";
wchar_t *stopwcs;
long l;
int base;
printf("wcs = \"%ls\"\n", wcs);
for (base=2; base<=8; base*=2) {
l = wcstol(wcs, &stopwcs, base);
printf(" wcstol = %ld\n"
" Stopped scan at \"%ls\"\n\n", l, stopwcs);
}
return 0;
/*******************************************************
The output should be similar to:
wcs = "10110134932"
wcstol = 45
Stopped scan at "34932"
wcstol = 4423
Stopped scan at "4932"
wcstol = 2134108
Stopped scan at "932"
*******************************************************/
}
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
- strtoul() – strtoull() — Convert Character String to Unsigned Long and Unsigned 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
- wcstoul() – wcstoull() — Convert Wide Character String to Unsigned Long and Unsigned Long Long Integer
- <wchar.h>