C++ <cwchar> - wcstol() Function

The C++ <cwchar> wcstol() function is used to interpret an integer value of the specified base in a wide string pointed to by str.

The function first discards any whitespace characters (as determined by iswspace()) until the first non-whitespace character is found. Then, starting from this character, takes an optional initial plus or minus sign followed by as many characters as possible to form a valid integer number (of specified base) representation and converts them to an integer value.

The valid integer value consists of the following parts:

• (optional) plus or minus sign
• (optional) prefix indicating octal or hexadecimal base ("0" or "0x"/"0X" respectively)
• a sequence of digits.

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

For locales other than the "C" locale, additional numeric formats may be accepted.

If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

If str_end is not a null pointer, the function also sets the value of str_end to point to the first character after the number. If str_end is a null pointer, it is ignored.

If the first sequence of non-whitespace characters in str is not a valid integral number, or if no such sequence exists (because either empty or contains only whitespaces), no conversion is performed and zero is returned.

Syntax

long int wcstol (const wchar_t* str, wchar_t** str_end, int base);

Parameters

Return Value

On success, the function returns the converted integral number as a value of type long int. If no conversion can be performed, zero (0L) is returned. If the converted value falls out of the range, LONG_MAX or LONG_MIN is returned, and errno is set to ERANGE.

Example 1:

The example below shows the usage of <cwchar> wcstol() function.

#include <cwchar>

int main (){
  wchar_t str1[] = L"123";
  wchar_t str2[] = L"10.55";
  wchar_t str3[] = L"100 some words";
  wchar_t str4[] = L"some words 555";

  wchar_t *end;

  long int num1 = wcstol(str1, &end, 10);
  long int num2 = wcstol(str2, &end, 10);
  long int num3 = wcstol(str3, &end, 10);
  long int num4 = wcstol(str4, NULL, 10);

  //displaying the result
  wprintf(L"wcstol(\"%ls\") = %ld\n", str1, num1);
  wprintf(L"wcstol(\"%ls\") = %ld\n", str2, num2);
  wprintf(L"wcstol(\"%ls\") = %ld\n", str3, num3);
  wprintf(L"wcstol(\"%ls\") = %ld\n", str4, num4);

  return 0;
}

The output of the above code will be:

wcstol("123") = 123
wcstol("10.55") = 10
wcstol("100 some words") = 100
wcstol("some words 555") = 0

Example 2:

Consider the example below where the wide string contains multiple integral values. The second parameter if not a null pointer then this function sets this parameter to value which points to the first character after the interpreted number. This feature can be used to interpret multiple integral values from the wide string.

#include <cwchar>

int main (){
  wchar_t str[] = L"123 10 -555";
  wchar_t *pEnd;

  long int val1 = wcstol(str, &pEnd, 10);
  long int val2 = wcstol(pEnd, &pEnd, 10);
  long int val3 = wcstol(pEnd, &pEnd, 10);

  //displaying the result
  wprintf(L"val1 = %ld\n", val1);
  wprintf(L"val2 = %ld\n", val2);
  wprintf(L"val3 = %ld\n", val3);

  return 0;
}

The output of the above code will be:

val1 = 123
val2 = 10
val3 = -555

Example 3:

Consider one more example where the third parameter of this function is used to interpret integral values in different bases.

#include <cwchar>

int main (){
  wchar_t str[] = L"11011 55 -123 ff 0xff";
  wchar_t *pEnd;

  long int val1 = wcstol(str, &pEnd, 2);
  long int val2 = wcstol(pEnd, &pEnd, 8);
  long int val3 = wcstol(pEnd, &pEnd, 10);
  long int val4 = wcstol(pEnd, &pEnd, 16);
  long int val5 = wcstol(pEnd, &pEnd, 0);

  //displaying the result
  wprintf(L"val1 = %ld\n", val1);
  wprintf(L"val2 = %ld\n", val2);
  wprintf(L"val3 = %ld\n", val3);
  wprintf(L"val4 = %ld\n", val4);
  wprintf(L"val5 = %ld\n", val5);

  return 0;
}

The output of the above code will be:

val1 = 27
val2 = 45
val3 = -123
val4 = 255
val5 = 255