atof, strtod, strtold, atoff, or strtof Subroutine

Purpose

Converts an ASCII string to a floating-point or double floating-point number.

Libraries

Standard C Library (libc.a)

Syntax

#include <stdlib.h>

double atof (NumberPointer)
const char *NumberPointer;

double strtod (NumberPointer, EndPointer)
const char *NumberPointer
char**EndPointer;

long double strtold (NumberPointer, EndPointer)
char *NumberPointer, **EndPointer;

float atoff (NumberPointer)
char *NumberPointer;

float strtof (NumberPointer, EndPointer)
char *NumberPointer, **EndPointer;

Description

The atof subroutine and strtod subroutine convert a character string, pointed to by the NumberPointer parameter, to a double-precision floating-point number. Similarly, the strtold subroutine converts a character string to a long double-precision floating-point number. The atoff subroutine and strtof subroutine convert a character string, pointed to by the NumberPointer parameter, to a single-precision floating-point number. The first unrecognized character ends the conversion.

Except for behavior on error, the atof subroutine is equivalent to the strtod subroutine call, with the EndPointer parameter set to (char**) NULL.

Except for behavior on error, the atoff subroutine is equivalent to the strtof subroutine call, with the EndPointer parameter set to (char**) NULL.

These subroutines recognize a character string when the characters are in one of two formats: numbers or numeric symbols.

• For a string to be recognized as a number, it should contain the following pieces in the following order:
  1. An optional string of white-space characters
  2. An optional sign
  3. A nonempty string of digits optionally containing a radix character
  4. An optional exponent in E-format or e-format followed by an optionally signed integer.
• For a string to be recognized as a numeric symbol, it should contain the following pieces in the following order:
  1. An optional string of white-space characters
  2. An optional sign
  3. One of the strings: INF, infinity, NaNQ, NaNS, or NaN (case insensitive)

Parameters

Return Values

Upon successful completion, the atof, atoff, strtod, strtold, and strtof subroutines return the converted value. If no conversion could be performed, a value of 0 is returned and the errno global variable is set to indicate the error.

Error Codes

Note: Because a value of 0 can indicate either an error or a valid result, an application that checks for errors with the strtod, strtof, and strtold subroutines should set the errno global variable equal to 0 prior to the subroutine call. The application can check the errno global variable after the subroutine call.

If the string pointed to by NumberPointer is empty or begins with an unrecognized character, a value of 0 is returned for the strtod, strtof, and strtold subroutines.

If the conversion cannot be performed, a value of 0 is returned, and the errno global variable is set to indicate the error.

If the conversion causes an overflow (that is, the value is outside the range of representable values), +/- HUGE_VAL is returned with the sign indicating the direction of the overflow, and the errno global variable is set to ERANGE.

If the conversion would cause an underflow, a properly signed value of 0 is returned and the errno global variable is set to ERANGE.

For the strtod, strtof, and strtold subroutines, if the value of the EndPointer parameter is not (char**) NULL, a pointer to the character that stopped the subroutine is stored in *EndPointer. If a floating-point value cannot be formed, *EndPointer is set to NumberPointer.

The atoff and strtof subroutines have only one rounding error. (If the atof or strtod subroutines are used to create a double-precision floating-point number and then that double-precision number is converted to a floating-point number, two rounding errors could occur.)

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

The atoff and strtof subroutines are not part of the ANSI C Library. These subroutines are at least as accurate as required by the IEEE Standard for Binary Floating-Point Arithmetic. The atof and strtod subroutines accept at least 17 significant decimal digits. The atoff and strtof subroutines accept at least 9 leading 0's. Leading 0's are not counted as significant digits.

Related Information

The scanf subroutine, strtol, strtoul, atol, or atoi subroutine, wstrtol, watol, or watoi subroutine.

Subroutines Overview in AIX General Programming Concepts: Writing and Debugging Programs.

128-Bit long double Floating-Point Format in AIX General Programming Concepts: Writing and Debugging Programs.