C Standard Library

C <wchar.h> - wcstold() Function



The C <wchar.h> wcstold() function is used to interpret a floating-point value 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 floating-point representation and converts them to a floating-point value.

The valid floating-point value for this function using the "C" locale is formed by an optional sign character (+ or -), followed by one of:

  • A sequence of digits, optionally containing a decimal-point character (.), optionally followed by an exponent part (an e or E character followed by an optional sign and a sequence of digits).
  • A 0x or 0X prefix, then a sequence of hexadecimal digits (as in iswxdigit()) optionally containing a period which separates the whole and fractional number parts. Optionally followed by a power of 2 exponent (a p or P character followed by an optional sign and a sequence of hexadecimal digits).
  • INF or INFINITY (ignoring case).
  • NAN or NANsequence (ignoring case), where sequence is a sequence of characters, where each character is either an alphanumeric character (as in isalnum) or the underscore character (_).

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 floating-point number, or if no such sequence exists (because either empty or contains only whitespaces), no conversion is performed and zero is returned.

Note: This function is wide character equivalent of strtold() function.

Syntax

long double wcstold (const wchar_t* str, wchar_t** str_end);

Parameters

str Specify pointer to the null-terminated wide string to be interpreted.
str_end Specify pointer to a pointer to a wide character.

Return Value

On success, the function returns the converted floating-point number as a value of type long double. If no conversion can be performed, 0.0 is returned. If the converted value falls out of the range, a positive or negative HUGE_VAL is returned, and errno is set to ERANGE.

Example 1:

The example below shows the usage of <wchar.h> wcstold() function.

#include <wchar.h>

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 str5[] = L"inF";
  wchar_t str6[] = L"Nan(2)";

  wchar_t *end;

  long double num1 = wcstold(str1, &end);
  long double num2 = wcstold(str2, &end);
  long double num3 = wcstold(str3, &end);
  long double num4 = wcstold(str4, NULL);
  long double num5 = wcstold(str5, NULL);
  long double num6 = wcstold(str6, NULL);

  //displaying the result
  wprintf(L"wcstold(\"%ls\") = %.2Lf\n", str1, num1);
  wprintf(L"wcstold(\"%ls\") = %.2Lf\n", str2, num2);
  wprintf(L"wcstold(\"%ls\") = %.2Lf\n", str3, num3);
  wprintf(L"wcstold(\"%ls\") = %.2Lf\n", str4, num4);
  wprintf(L"wcstold(\"%ls\") = %.2Lf\n", str5, num5);
  wprintf(L"wcstold(\"%ls\") = %.2Lf\n", str6, num6);

  return 0;
}

The output of the above code will be:

wcstold("123") = 123.00
wcstold("10.55") = 10.55
wcstold("100 some words") = 100.00
wcstold("some words 555") = 0.00
wcstold("inF") = inf
wcstold("Nan(2)") = nan

Example 2:

Consider one more example where the string contains multiple floating-point 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 floating-point values from the string.

#include <wchar.h>

int main (){
  wchar_t str[] = L"123 10.55 555.89";
  wchar_t *pEnd;

  long double val1 = wcstold(str, &pEnd);
  long double val2 = wcstold(pEnd, &pEnd);
  long double val3 = wcstold(pEnd, &pEnd);

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

  return 0;
}

The output of the above code will be:

val1 = 123.00
val2 = 10.55
val3 = 555.89

❮ C <wchar.h> Library