atof atoff 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;
float atoff (NumberPointer)
char *NumberPointer;

Description

The atof subroutine converts a character string, pointed to by the NumberPointer parameter, to a double-precision floating-point number. The atoff subroutine converts 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)

The atoff subroutine is 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 subroutine accepts at least 17 significant decimal digits. The atoff and subroutine accepts at least 9 leading 0's. Leading 0's are not counted as significant digits.

Note: Starting with the IBM® AIX® 6 with Technology Level 7 and the IBM AIX 7 with Technology Level 1, the precision of the floating-point conversion routines, printf and scanf family of functions has been increased from 17 digits to 37 digits for double and long double values.

Parameters

Item Description
NumberPointer Specifies a character string to convert.
EndPointer Specifies a pointer to the character that ended the scan or a null value.

Return Values

Upon successful completion, the atof, and atoff 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

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.

The atoff subroutine has only one rounding error. (If the atof subroutine is 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.)