wcstol - Convert a wide-character string to long integer
#include <wchar.h>
long int wcstol(
const wchar_t *nptr,
wchar_t **endptr,
int base );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
wcstol(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
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 parameter where a wide
character is found that is not a valid character for the
purpose of this conversion. Specifies the radix in which
the characters are interpreted.
The wcstol() function converts the initial portion of the
wide-character string pointed to by the nptr parameter to
a long integer representation. The input wide-character
string is first broken down into three parts: White
space--An initial (possibly empty) sequence of wide-character
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 specified 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 example, 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, following the sign, if present.
The wide-character string is parsed to skip the initial
space characters (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.)
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 successful, 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.
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 converted value is outside the range of representable
values.
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);
}
} }
Functions: atoi(3), iswalnum(3), scanf(3), wcstod(3),
wcstoul(3), wctype(3), wscanf(3)
Standards: standards(5)
wcstol(3)
[ Back ] |