function
<cstdlib>

strtof

float strtof (const char* str, char** endptr);
Convert string to float
Parses the C-string str interpreting its content as a floating point number (according to the current locale) and returns its value as a float. If endptr is not a null pointer, the function also sets the value of endptr to point to the first character after the number.

The function first discards as many whitespace characters (as in isspace) as necessary until the first non-whitespace character is found. Then, starting from this character, takes as many characters as possible that are valid following a syntax resembling that of floating point literals (see below), and interprets them as a numerical value. A pointer to the rest of the string after the last valid character is stored in the object pointed by endptr.

A valid floating point number for strtof 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 isxdigit) 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 the first sequence of non-whitespace characters in str does not form a valid floating-point number as just described, or if no such sequence exists because either str is empty or contains only whitespace characters, no conversion is performed and the function returns 0.0F.

Parameters

str
C-string beginning with the representation of a floating-point number.
endptr
Reference to an already allocated object of type char*, whose value is set by the function to the next character in str after the numerical value.
This parameter can also be a null pointer, in which case it is not used.

Return Value

On success, the function returns the converted floating point number as a value of type float.
If no valid conversion could be performed, the function returns zero (0.0F).
If the correct value is out of the range of representable values for the type, a positive or negative HUGE_VALF is returned, and errno is set to ERANGE.
If the correct value would cause underflow, the function returns a value whose magnitude is no greater than the smallest normalized positive number (some library implementations may also set errno to ERANGE in this case).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/* strtof example */
#include <stdio.h>      /* printf, NULL */
#include <stdlib.h>     /* strtof */

int main ()
{
  char szOrbits[] = "686.97 365.24";
  char* pEnd;
  float f1, f2;
  f1 = strtof (szOrbits, &pEnd);
  f2 = strtof (pEnd, NULL);
  printf ("One martian year takes %.2f Earth years.\n", f1/f2);
  return 0;
}

Output:
One martian year takes 1.88 Earth years.


Data races

The array pointed by str is accessed, and the pointer pointed by endptr is modified (if not null).

Exceptions (C++)

No-throw guarantee: this function never throws exceptions.

If str does not point to a valid C-string, or if endptr does not point to a valid pointer object, it causes undefined behavior.

See also