C++ wcstod()

The wcstod() function in C++ interprets the contents of a wide string as a floating point number and return its value as a double.

The wcstod() function also sets a pointer to point to the first wide character after the last valid character of the wide string if there is any, otherwise the pointer is set to null.

It is defined in <cwchar> header file.

wcstod() prototype

double wcstod( const wchar_t* str, wchar_t** str_end );

The wcstod() function takes wide string and a pointer to wide character as its parameter, interprets the content of the wide string as a floating point number and returns a double value.


wcstod() Parameters

  • str: A wide string having the representation of a floating point number.
  • str_end: Pointer to a pointer to a wide character. The value of str_end is set by the function to the next character in str after the last valid character. This parameter can also be a null pointer.

wcstod() Return value

The wcstod() function returns:

  • a double value (which is converted from the wide string).
  • 0.0 if no valid conversion could be performed.

If the converted value is out of the range, a range error occurs and a positive or negative HUGE_VAL is returned.


Example 1: How wcstod() function works?

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t str[] = L"83.201xz\u0496\u0687";

	wchar_t *end;
	double value;
	value = wcstod(str,&end);

	wcout << L"Wide String = " << str << endl;
	wcout << L"Double value = " << value << endl;
	wcout << L"End String = " << end << endl;
	
	return 0;
}

When you run the program, the output will be:

Wide String = 83.201xzҖڇ
Double value = 83.201
End String = xzҖڇ

Example 2: wcstod() function without trailing characters

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t str[] = L"83.201";

	wchar_t *end;
	double value;
	value = wcstod(str,&end);

	wcout << L"Wide String = " << str << endl;
	wcout << L"Double value = " << value << endl;
	wcout << L"End String = " << end << endl;

	return 0;
}

When you run the program, the output will be:

Wide String = 83.201
Double value = 83.201
End String =

A valid floating-point value for wcstod() function consists of an optional + or - sign followed by one of the following sets:

  • For decimal floating-point value:
    • A group of decimal digits (0-9), optionally containing a decimal point (.). For example: 13.170, -5.63, etc .
    • An optional exponent part (e or E) followed by an optional + or - sign and non-empty sequence of decimal digits. For example: 3.46101e+007, 13.19e-013, etc.
  • For hexadecimal floating-point value:
    • A string starting with 0x or 0X, followed by a non-empty sequence of hexadecimal digits, optionally containing a decimal point (.). For Example: 0xfa5, -0xb1f.24, etc.
    • An optional exponent part (p or P) followed by an optional + or - sign and non-empty sequence of hexadecimal digits. For Example: 0x51c.23p5, -0x2a.3p-3, etc.
  • Infinity:
    • INF or INFINITY (ignoring case). For Example: -Inf, InfiNiTy, etc.
  • NaN (Not a Number):
    • NAN or NANsequence (ignoring case) where sequence is a sequence of characters consisting only of alphanumeric characters or the underscore (_).The result is a quiet NaN. For Example: Nan, NaNab1, etc.

Example 3: How wcstod() works with exponents and hexadecimals?

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t str1[] = L"-136.31e-2End\u03c8";
	wchar_t str2[] = L"0x11a.2c\u05ea";
	wchar_t *end;
	double value;

	value = wcstod(str1,&end);
	wcout << L"Wide String = " << str1 << endl;
	wcout << L"Double value = " << value << endl;
	wcout << L"End String = " << end << endl;

	value = wcstod(str2,&end);
	wcout << L"Wide String = " << str2 << endl;
	wcout << L"Double value = " << value << endl;
	wcout << L"End String = " << end << endl;
	
	return 0;
}

When you run the program, the output will be:

Wide String = -136.31e-2Endψ
Double value = -1.3631
End String = Endψ
Wide String = 0x11a.2cת
Double value = 282.172
End String = ת

Example 4: wcstod Cases for INFINITY and NaN

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t str1[] = L"-inFinityx\u03a3y";
	wchar_t str2[] = L"NaN11\u0429";
	wchar_t *end;
	double value;

	value = wcstod(str1,&end);
	wcout << L"Wide String = " << str1 << endl;
	wcout << L"Double value = " << value << endl;
	wcout << L"End String = " << end << endl;

	value = wcstod(str2,&end);
	wcout << L"Wide String = " << str2 << endl;
	wcout << L"Double value = " << value << endl;
	wcout << L"End String = " << end << endl;
	
	return 0;
}

When you run the program, the output will be:

Wide String = -inFinityxΣy
Double value = -inf
End String = xΣy
Wide String = NaN11Щ
Double value = nan
End String = 11Щ

In general, a valid floating point argument for wcstod() function has the following form:

[whitespace] [- | +] [digits] [.digits] [ {e | E }[- | +]digits]

The wcstod() function ignores all the leading whitespace characters until the primary non-whitespace character is found.

Then, beginning from this character, it takes as many characters as possible that forms a valid floating-point representation and converts them to a floating point value. Whatever is left of the string after the last valid character is stored in the object pointed by str_end.


Example 5: wcstod() function with leading whitespace

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t str[] = L" 21.69\u04f8aa";

	wchar_t *end;
	double value;

	value = wcstod(str,&end);
	wcout << L"Wide String = " << str << endl;
	wcout << L"Double value = " << value << endl;
	wcout << L"End String = " << end << endl;
	
	return 0;
}

When you run the program, the output will be:

Wide String = 21.69Ӹaa
Double value = 21.69
End String = Ӹaa