wcstoul - Convert wide-character strings to unsigned long
integer
#include <wchar.h>
unsigned long int wcstoul(
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:
wcstoul(): ISO C, XPG4
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 an unsigned long integer. Points to a pointer
in which the wcstoul() 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
wide characters are interpreted.
The wcstoul() function converts the initial portion of the
wide-character string pointed to by the nptr parameter to
an unsigned long integer representation. The input widecharacter
string is first broken down into three parts:
White space--An initial (possibly empty) sequence of widecharacter
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 unsigned
integer and the result is returned.
The base parameter can take values between 0 and 36 to
indicate the following: 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 base 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 cast to unsigned integer. 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
white-space characters (as determined by the iswspace()
function). Any nonspace character is the start of a
potential subject string that may form an unsigned long
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 unsigned 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 were the C locale. (Current
industry standards allow, but do not require, conforming
implementations to support forms of subject sequences outside
the base range that is supported by the POSIX locale.
Keep this fact in mind when developing applications to run
on different vendors' systems.)
The wcstoul() function returns the converted value of the
unsigned integer if the expected form is found. If no conversion
could be performed, a value of 0 (zero) is
returned. If the converted value is outside the range of
representable values, ULONG_MAX is returned.
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, wcstoul() stores the nptr
pointer in the *endptr parameter.
Since 0 (zero) and ULONG_MAX are returned in the event of
an error and are also valid returns if the wcstoul() function
is successful, applications should set errno to 0
(zero) before calling the wcstoul() function and check
errno after each return from the wcstoul() 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 wcstoul()
function sets errno to the corresponding value: The base
parameter has a value less than 0 or greater than 36.
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
unsigned long integer:
#include <stdio.h> #include <wchar.h> #include <locale.h>
#include <errno.h> #define WLENGTH 40
main() {
wchar_t WCString[WLENGTH], *endptr;
unsigned long int retval;
(void)setlocale(LC_ALL, " ");
if (fgetws(WCString, WLENGTH, stdin) != NULL) {
errno = 0;
retval = wcstoul ( WCString, &endptr, 0 );
if (retval == 0 && (errno != 0
|| WCString == endptr)) {
/* No conversion could be performed */
printf("No conversion performed\n");
} else if (retval == ULONG_MAX && errno != 0 ) {
/* Error handling */
} else {
/* retval contains an unsigned long integer */
printf("Unsigned integer in decimal is %lx\n",
retval); }
} }
Functions: atoi(3), iswalnum(3), scanf(3), wcstod(3),
wcstol(3), wctype(3), wscanf(3)
Standards: standards(5)
wcstoul(3)
[ Back ] |
