[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2


wcstol or wcstoll Subroutine

Purpose

Converts a wide-character string to a long integer representation.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>


long int wcstol ( Nptr Endptr Base)
const wchar_t *Nptr;
wchar_t **Endptr;
int Base;

long long int wcstoll (*Nptr, **Endptr, Base)
const wchar_t *Nptr;
wchar_t **Endptr:
int Base

Description

The wcstol subroutine converts a wide-character string to a long integer representation. The wcstoll subroutine converts a wide-character string to a long long integer representation.

  1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by the iswspace subroutine)
  2. A subject sequence interpreted as an integer and represented in a radix determined by the Base parameter
  3. A final wide-character string of one or more unrecognized wide-character codes, including the terminating wide-character null of the input wide-character string

If possible, the subject is then converted to an integer, and the result is returned.

The Base parameter can take the following values: 0 through 9, or 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 a decimal, octal, or hexadecimal constant, any of which can be preceded by a + (plus sign) or - (minus sign). A decimal constant starts with a non zero digit, and is composed of a sequence of decimal digits. An octal constant consists of the prefix 0 optionally followed by a sequence of the digits 0 to 7. A hexadecimal constant is defined as the prefix 0x (or 0X) followed by a sequence of decimal digits and the letters a (or A) to f (or F) with values ranging from 10 (for a or A) to 15 (for f or F).

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 in 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 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 the iswspace subroutine). Any non-space character signifies the start of a subject string that may form an integer in the radix specified by the Base parameter. The subject sequence is defined to be the longest initial substring that is a long integer of the expected form. Any character not satisfying this form begins the final portion of the wide-character string pointed to by the Endptr parameter on return from the call to the wcstol or wcstoll subroutine.

Parameters


Nptr Contains a pointer to the wide-character string to be converted to a long integer number.
Endptr Contains a pointer to the position in the Nptr parameter string where a wide-character is found that is not a valid character.
Base Specifies the radix in which the characters are interpreted.

Return Values

The wcstol and wcstoll subroutines return the converted value of the 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, LONG_MAX or LONG_MIN is returned (according to the sign of the value), and the value of errno is set to ERANGE. If the base value specified by the Base parameter is not supported, EINVAL is returned.

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. The value of the Nptr parameter is stored in the Endptr parameter if that parameter is not a null pointer.

Since 0, LONG_MIN, and LONG_MAX are returned in the event of an error and are also valid returns if the wcstol or wcstoll subroutine is successful, applications should set the errno global variable to 0 before calling either subroutine, and then check errno after return. If the errno global value has changed, an error occurred.

Examples

To convert a wide-character string to a signed long integer, use the following code:

#include <stdlib.h>
#include <locale.h>
#include <errno.h>

main()
{
        wchar_t *WCString, *endptr;
        long int retval;
        (void)setlocale(LC_ALL, "");
        /**Set errno to 0 so a failure for wcstol can be
        **detected */
        errno=0;
        /*
        **Let WCString point to a wide character null terminated
        ** string containing a signed long integer value
        ** 
                */retval = wcstol ( WCString &endptr, 0 );
        /* Check errno, if it is non-zero, wcstol failed */
        if (errno != 0) {
                /*Error handling*/
        }
        else if (&WCString == endptr) {
                /* No conversion could be performed */
                /* Handle this case accordingly. */
        }
        /* retval contains long integer */
}

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The iswspace subroutine, wcstod (wcstod Subroutine) subroutine, wcstoul (wcstoul or wcstoull Subroutine) subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character String Conversion Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]