6.23.54 wcstoul Function

Convert wide string to an unsigned long integer value.

Attention: This function is implemented only by MPLAB XC32 C compilers.

Include

<wchar.h>

Prototype

unsigned long int wcstoul(const wchar_t * restrict nptr, wchar_t ** restrict endptr, int base);

Arguments

nptr: the wide string to attempt to convert
endptr: pointer to store the address of the remainder of the wide string that was not converted
base: the radix in which the value of the wide string should be interpreted

Return Value

The converted value, or 0 if the conversion could not be performed. If the correct value of the conversion is outside the range of representable values, ULONG_MAX is returned.

Remarks

The wcstoul function attempts to convert a portion of the wide string pointed to by nptr to a unsigned long intvalue.

The initial sequence consists of any white-space wide characters.

The subject sequence represents the integer constant to convert and whose radix is given by base.

If the value of base is zero, the expected form of the subject sequence is that of an integer constant whose radix is determined by the sequence itself. For example, a leading 0x implies a hexadecimal constant; a leading 0 implies an octal constant. The sequence may be preceded by a plus or minus sign, but not including an integer suffix.

If the value of base is between 2 and 36 (inclusive), the expected form of the subject sequence is a sequence of letters (a (or A) through z (or Z) ascribed the values 10 through 35) and digits representing an integer with the radix specified by base. Only letters and digits whose ascribed values are less than that of base are permitted. The sequence may be preceded by a plus or minus sign, but not including an integer suffix. If the value of base is 16, the wide characters 0x or 0X may prefix the sequence of letters and digits, following the sign wide character if present.

Conversion stops once an unrecognized wide character is encountered, thus the subject sequence is defined as the longest subsequence of the input wide string after the initial sequence and that is of the expected form. A pointer to the position of the first unrecognizable wide character in the wide string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.

The final sequence consists of wide characters in the wide string that were unrecognized in the subject sequence and which will include the terminating null wide character of the wide string. This sequence of the wide string will be accessible via the address stored to endptr, provided endptr is not a null pointer.

The value of the macro ERANGE is stored in errno if the correct value of the conversion is outside the range of representable values.

Example

#include <wchar.h>

int main ()
{
  wchar_t ws[] = L"2001 60c0c0 -1101110100110100100000 7000 07000";
  wchar_t * pEnd;
  unsigned long int uli1, uli2, uli3, uli4, uli5;

  uli1 = wcstoul(ws, &pEnd, 10);
  uli2 = wcstoul(pEnd, &pEnd, 16);
  uli3 = wcstoul(pEnd, &pEnd, 2);
  uli4 = wcstoul(pEnd, &pEnd, 16);
  uli5 = wcstoul(pEnd, NULL, 0);
  wprintf(L"The converted string values in decimal are: %lu, %lu, %lu, %lu, and %lu.\n", uli1, uli2, uli3, uli4, uli5);
}

Example Output

The converted string values in decimal are: 2001, 6340800, 18446744073705927392, 28672, and 3584.