wcstol(3)wcstol(3)NAMEwcstol - Convert a wide-character string to long integer
SYNOPSIS
#include <wchar.h>
long int wcstol(
const wchar_t *nptr,
wchar_t **endptr,
int base );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
wcstol(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Contains a pointer to the wide-character string to be converted to a
long integer representation. Points to a pointer in which the wcstol()
function stores the position in the string specified by the nptr param‐
eter where a wide character is found that is not a valid character for
the purpose of this conversion. Specifies the radix in which the char‐
acters are interpreted.
DESCRIPTION
The wcstol() function converts the initial portion of the wide-charac‐
ter string pointed to by the nptr parameter to a long integer represen‐
tation. The input wide-character string is first broken down into three
parts: White space--An initial (possibly empty) sequence of wide-char‐
acter spaces (as specified by the iswspace() function) Subject
sequence--A sequence of wide characters that are valid in an integer
constant of the radix determined by the base parameter Unrecognized
characters--A final sequence of unrecognized wide-character codes,
including the terminating null wide character
If possible, the subject is then converted to an integer and the result
is returned.
The base parameter can take values between 0 and 36. If the base value
is 0 (zero), the subject string can be a decimal, octal, or hexadecimal
integer constant. A decimal constant begins with a nonzero digit and
consists of a sequence of decimal digits. An octal constant consists of
the prefix 0 (zero) optionally followed by a sequence of digits in the
range 0 through 7. A hexadecimal constant consists of the prefix 0x or
oX followed by a sequence consisting of decimal digits and the letters
in the range a (or A) to f (or F). If the base value is between 2 and
36, the subject string can be a sequence of digits and the letters a
(or A) to z ( or Z ) that are used to represent an integer in the spec‐
ified base. Alphabetic characters represent digits with an equivalent
decimal value from 10 (for the letter A) to 35 (for the letter Z). The
subject string can have only digits with a value less than base and
alphabetic characters with equivalent values less than base. For exam‐
ple, when the value of the base parameter is 20, only the following
value assignments are converted:
Character 0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J
a b c d e f g h i j
Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
The subject string can optionally be preceded by a + (plus sign) or -
(minus sign), but cannot include an integer suffix (such as L). If the
subject string is preceded by a - (minus sign), the converted integer
value has a negative value. If the value of base is 16, the characters
0x or 0X may optionally precede the sequence of letters or digits, fol‐
lowing the sign, if present.
The wide-character string is parsed to skip the initial space charac‐
ters (as determined by theiswspace() function). Any nonspace character
is the start of a potential subject string that may form an integer in
the base specified by the base parameter. The subject sequence is
defined to be the longest initial substring that is of the expected
form of long integer. Any character that does not satisfy this expected
form begins the final sequence of unrecognized characters. The wcstol()
function sets the *endptr parameter to point to this final sequence of
unrecognized characters.
If the subject sequence is empty or does not have the expected form,
the function performs no conversion. In this case, provided that endptr
is not a null pointer, the function stores the value of nptr in the
object pointed to by endptr.
The LC_CTYPE category of the locale controls which wide characters are
treated as spaces but does not affect the interpretation of characters
as part of the subject string. The characters in the subject string are
always treated as if the locale was the POSIX (C) locale. (Current
industry standards allow conforming implementations to support forms of
subject sequences in addition to those in the POSIX (C) locale. On
Tru64 UNIX systems, this additional support is unnecessary.)
RETURN VALUES
If the wcstol() function finds the expected subject form, the converted
value of long integer is returned. The function returns 0 (zero) if it
does not convert the subject value. If the converted value is outside
the range of representable values, the function returns LONG_MAX or
LONG_MIN (according to the sign of the subject value).
If the endptr parameter is not a null pointer, wcstol() stores a
pointer to the final sequence of unrecognized characters in *endptr
except when the subject sequence is empty or invalid. In this case,
wcstol() stores the nptr pointer in the *endptr parameter.
Since 0 (zero), LONG_MIN, and LONG_MAX are returned in the event of an
error and are also valid returns if the wcstol() function is success‐
ful, applications should set errno to 0 (zero) before each call to the
wcstol() function, and check errno after each return from the wcstol()
function. If errno is nonzero, an error occurred. Additionally, if 0
(zero) is returned, applications should check if the endptr parameter
equals the nptr parameter. In this case, there was no valid subject
string.
ERRORS
If any of the following conditions occur, the wcstol() function sets
errno to the corresponding value: The base parameter has an unsupported
value (less than 0 or greater than 36).
[Tru64 UNIX] The nptr parameter is a null pointer. The con‐
verted value is outside the range of representable values.
EXAMPLES
The following example converts a wide-character string to a signed long
integer:
#include <stdio.h> #include <wchar.h> #include <locale.h> #include
<errno.h> #define WLENGTH 40
main {
wchar_t WCString[WLENGTH], *endptr;
long int retval;
(void)setlocale(LC_ALL, "");
if (fgetws(WCString, WLENGTH, stdin) != NULL) {
errno = 0;
retval = wcstol ( WCString, &endptr, 0 );
if (retval == 0 && (errno != 0
|| WCString == endptr)) {
/* No conversion could be performed */
printf("No conversion performed\n");
} else if (errno != 0 && (retval == LONG_MAX
|| retval == LONG_MIN)) {
/* Error handling */
} else {
/* retval contains long integer */
printf("Integer in decimal is %d\n", retval);
}
} }
SEE ALSO
Functions: atoi(3), iswalnum(3), scanf(3), wcstod(3), wcstoul(3),
wctype(3), wscanf(3)
Standards: standards(5)wcstol(3)
