strtod() — Convert character string to double

Standards

Standards / Extensions C or C++ Dependencies
ISO C
XPG4
XPG4.2
C99
Single UNIX Specification, Version 3
 both  

Format

#include <stdlib.h>

double strtod(const char * __restrict__nptr, char ** __restrict__endptr);

General description

Converts a part of a character string, pointed to by nptr, to a double. The parameter nptr points to a sequence of characters that can be interpreted as a numerical value of the type double.

See the “fscanf Family of Formatted Input Functions” on fscanf(), scanf(), sscanf() — Read and format data for a description of special infinity and NaN sequences recognized by z/OS® formatted input functions, including atof() and strtod() in IEEE Binary Floating-Point mode.

The strtod() function breaks the string into three parts:
  1. A sequence of white space characters (as specified for the current locale, see isspace())
  2. A subject sequence interpreted as a floating-point constant or representing infinity or a NAN.
  3. A sequence of unrecognized characters (including a NULL character).

The subject string is the longest string that matches the expected form.

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 part. Where radix character is the character that separates the integer part of a number from the fractional part.
  • A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally containing a radix character, then an optional binary exponent part. Where radix character is the character that separates the integer part of a number from the fractional part.
  • One of INF or INFINITY, ignoring case.
  • One of NANQ or NANQ(n-char-sequence), ignoring case.
  • One of NANS or NANS(n-char-sequence), ignoring case.
  • One of NAN or NAN(n-char-sequence), ignoring case.

The pointer to the last string successfully converted is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer. If the subject string is empty or it does not have the expected form, then no conversion is performed. The value of nptr is stored in the object pointed to by endptr.

Returned value

If successful, strtod() returns the value of the floating-point number.

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

In an overflow, strtod() returns ±HUGE_VAL. In an underflow, it returns 0. If no conversion is performed, strtod() returns 0. In both cases, errno is set to ERANGE, depending on the base of the value.

Example

CELEBS53 
/* CELEBS3                                      

   This example converts a string to a double value.                            
   It prints out the converted value and the substring that                     
   stopped the conversion.                                                      
                                                                                
 */                                                                             
#include <stdlib.h>                                                             
#include <stdio.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   char *string, *stopstring;                                                   
   double x;                                                                    
                                                                                
   string = "3.1415926This stopped it";                                         
   x = strtod(string, &stopstring);                                             
   printf("string = %s\n", string);                                             
   printf("   strtod = %f\n", x);                                               
   printf("   Stopped scan at %s\n\n", stopstring);                             
                                                                                
   string = "100ergs";                                                          
   x = strtod(string, &stopstring);                                             
   printf("string = \"%s\"\n", string);                                         
   printf("   strtod = %f\n", x);                                               
   printf("   Stopped scan at \"%s\"\n\n", stopstring);                         
}
Output 
string = 3.1415926This stopped it
   strtod = 3.141593
   Stopped scan at This stopped it

string = 100ergs
   strtod = 100.000000
   Stopped scan at ergs

Related information