wcstoul or wcstoull Subroutine

Purpose

Converts wide character strings to unsigned long or long long integer representation.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>

unsigned long long int wcstoull (Nptr, Endptr, Base)
const wchar_t *Nptr;
wchar_t **Endptr;
int Base;

Description

The wcstoul and wcstoull subroutines convert the initial portion of the wide character string pointed to by the Nptr parameter to an unsigned long or long long integer representation. To do this, it parses the wide character string pointed to by the Nptr parameter to obtain a valid string (that is, subject string) for the purpose of conversion to an unsigned long integer. It then points the Endptr parameter to the position where an unrecognized character, including the terminating null, is found.

The base specified by the Base parameter can take the following values: 0 through 9, a (or A) through z (or Z). There are potentially 36 values for the base. If the base value is 0, the expected form of the subject string is that of an unsigned integer constant, with an optional + (plus sign) or - (minus sign), but not including the integer suffix. If the base value is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by the Base parameter, optionally preceded by a + or -, but not including an integer suffix.

The letters a (or A) through z (or Z) are ascribed the values of 10 to 35. Only letters whose values are less than that of the base are permitted. If the value of the base is 16, the characters 0x (or 0X) may optionally precede the sequence of letters or digits, following a + or - . present.

The wide character string is parsed to skip the initial white-space characters (as determined by the iswspace subroutine). Any nonspace character signifies the start of a subject string that may form an unsigned long integer in the radix specified by the Base parameter. The subject sequence is defined to be the longest initial substring that is an unsigned long integer of the expected form. Any character not satisfying this expected form begins the final portion of the wide character string pointed to by the Endptr parameter on return from the call to this subroutine.

Parameters

Return Values

The wcstoul and wcstoull subroutines return the converted value of the unsigned long or long long integer if the expected form is found. If no conversion could be performed, a value of 0 is returned. If the converted value is outside the range of representable values, a ULONG_MAX value is returned (for wcstoul), and ULLONG_MAX is returned (for wcstoull), and the value of the errno global variable is set to a ERANGE value.

If the subject sequence has the expected form, it is interpreted as an integer constant in the appropriate base. A pointer to the final string is stored in the Endptr parameter if that parameter is not a null pointer. If the subject sequence is empty or does not have a valid form, no conversion is done and the value of the Nptr parameter is stored in the Endptr parameter if it is not a null pointer.

If the radix specified by the Base parameter is not supported, an EINVAL value is returned. If the value to be returned is not representable, an ERANGE value is returned.

Examples

To convert a wide character string to an unsigned long integer, use the following code:

#include <stdlib.h>
#include <locale.h>
#include <errno.h>
extern int errno;
 

main()
{
        wchar_t *WCString, *EndPtr;
        unsigned long int   retval;

        (void)setlocale(LC_ALL, "");
        /* 
        ** Let WCString point to a wide character null terminated
        ** string containing an unsigned long integer value.
        ** 
        */

        retval = wcstoul ( WCString  &EndPtr,  0 );
        if(retval==0) {
                /* No conversion could be performed */
                /* Handle this case accordingly. */
        } else if(retval == ULONG_MAX) {
                /* Error handling */
        }
        /* retval contains the unsigned long integer value. */
}