wcstoul(3)wcstoul(3)NAMEwcstoul - Convert wide-character strings to unsigned long integer
SYNOPSIS
#include <wchar.h>
unsigned long int wcstoul(
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:
wcstoul(): ISO C, XPG4
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 an
unsigned long integer. Points to a pointer in which the wcstoul()
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 wide
characters are interpreted.
DESCRIPTION
The wcstoul() function converts the initial portion of the wide-charac‐
ter string pointed to by the nptr parameter to an unsigned 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 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 dig‐
its. An octal constant consists of the prefix 0 (zero) optionally fol‐
lowed 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 con‐
sisting 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 charac‐
ters 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 con‐
verted.
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 unrecog‐
nized 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 sup‐
port forms of subject sequences outside the base range that is sup‐
ported by the POSIX locale. Keep this fact in mind when developing
applications to run on different vendors' systems.)
RETURN VALUES
The wcstoul() function returns the converted value of the unsigned
integer if the expected form is found. If no conversion could be per‐
formed, a value of 0 (zero) is returned. If the converted value is out‐
side 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, appli‐
cations should set errno to 0 (zero) before calling the wcstoul() func‐
tion 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.
ERRORS
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.
EXAMPLES
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);
}
} }
SEE ALSO
Functions: atoi(3), iswalnum(3), scanf(3), wcstod(3), wcstol(3),
wctype(3), wscanf(3)
Standards: standards(5)wcstoul(3)
