wcstof() — Convert a wide-character string to float

Standards

Standards / Extensions C or C++ Dependencies

C99
Single UNIX Specification, Version 3
C++ TR1 C99

 both z/OS® V1R7

Format

#define _ISOC99_SOURCE
#include <wchar.h>

float wcstof(const wchar_t *__restrict__ nptr, wchar_t **__restrict__ endptr);

General description

wcstof() converts a wchar_t * floating-point number input string to a float value. The parameter nptr points to a sequence of wide-characters that can be interpreted as a numerical float value.

It decomposes the input wide-character string into three parts:

  1. An initial, possibly empty, sequence of white-space character codes (as specified by iswspace()).
  2. A subject sequence resembling a floating-point constant, infinity, or NaN.
  3. A final wide-character string of one or more unrecognized wide-characters codes, including the terminating NULL wide-character of the input wide-character string.

The function then attempts to convert the subject string into the floating-point number, and returns the result.

The expected form of the subject sequence is an optional plus or minus sign, then one of the following:

  • A non-empty sequence of decimal digits optionally containing a radix character, then an optional exponent. A radix character is the character that separates the integer part of a number from the fractional part.
  • A 0x or 0X, a non-empty sequence of hexadecimal digits optionally containing a radix character, then a base 2 decimal exponent part with a p or P as prefix, a plus or minus sign, then a sequence of at least one decimal digit. (Example [-]0xh.hhhhp+/-d). A radix character is the character that separates the integer part of a number from the fractional part.
  • One INF or INFINITY, ignoring case.
  • One NANQ or NANQ(n-char-sequence), ignoring case.
  • One NANS or NANS(n-char-sequence), ignoring case.
  • One NAN or NAN(n-char-sequence), ignoring case.

See the "scanf() Family of Formatted Input Functions" for a description of special infinity and NaN sequences recognized by z/OS formatted input functions in IEEE Binary Floating-Point mode. A pointer to the final wide-character string is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer.

Returned value

If successful, wcstof() returns the converted value, if any. If no conversion could be performed, it returns 0.

The float value is a hexadecimal floating-point or IEEE Binary Floating-Point format depending on the floating-point mode of the thread invoking wcstof(). This function uses __isBFP() to determine the floating-point mode of the invoking thread.

If the correct value is outside the range of representable values, then +/-HUGE_VALF, according to the sign of the value, is returned and the value of the ERANGE macro is stored in errno. If the correct value would cause an underflow, 0 is returned and the value of the ERANGE macro is stored in errno.

Related information

Parent topic: Library functions