Simple Conversion Functions

These are the simplest functions for a C programmer to use, because they require no preparation or subsequent tests for conversion errors. With the exception of atof(3) on some UNIX platforms, the entire issue of conversion errors is ignored. For this reason, they are frequently not the best choice of conversion functions available.

Before the alternatives are explored, let's examine these traditional functions more closely.

Scrutinizing the Functions atoi(3) and atol(3)

The functions atoi(3) and atol(3) have the following synopsis:

#include <stdlib.h>

int atoi(const char *nptr);
long atol(const char *nptr);

These functions simply take the starting address of a C string and return the result as an int or a long data type value. Any leading whitespace characters, as defined by the C library function isspace(3), are skipped before the conversion is begun. If the conversion fails, the functions atoi(3) and atol(3) simply give up and return zero.

Using the atoi(3) Function

The following is a simple example of using the atoi(3) function:

char buf[32];
int i;

strcpy(buf,"23");
i = atoi(buf);

In this example, the string "23" is converted to an integer value 23 and assigned to the variable i. However, had the input string contained bad input, the value of i would not contain a meaningful result (zero).

Understanding the Conversion Error Problem

As an example, consider the problem where the function atoi(3) is used. Assume that there is a debug command-line option of the form -x n, where n is the debug level between 0 and 9. Within the getopt(3) processing loop, the optarg value for -x must be converted to an integer value.

switch( optch ) {
case 'x':
    cmdopt_x = atoi(optarg); /* Get debug level */
    break;

Assume that the user supplied the option as -x high on the command line because he didn't know any better. The atoi(3) function will glibly return the value 0 in this case because it cannot convert high to an integer numeric value. The program will be unaware that there should be a debug level set because the conversion value was 0 (due to the conversion error). Consequently, the program will run without any debug level at all. This results in a program action that is not user friendly.

Converting Garbled Data

A similar problem develops when the user supplies the debug option as -x 5oops because he is all thumbs on the keyboard. The program will glibly accept the value 5 that atoi(3) was able to convert successfully. The remaining part of the string oops is ignored.

The functions atoi(3), atol(3), and atof(3) all lack error return information. A better indication of when the conversion succeeded or failed is required.

Knowing Where the Conversion Ended

An additional limitation of the atoi(3) family of functions is that the caller is not given information about where the conversion ends in the input string. If it is necessary to write a function to extract the month, day, and year from a date string, you would have a challenge using the atoi(3) function. Consider the following variations in date strings that might be provided as input from a terminal:

• 01/01/2000

• 1/2/2000

• 12/1/2000

• 1/ 9/2000

• 1 / 31 / 2000

• 6-31-2001

The atoi(3) function can help only with the month extraction (assuming month/day/year format). After extracting the month, you are left with these questions: How many blanks were skipped over? How many digits were there? Were any trailing blanks present? Because no scan information is returned by atoi(3), your code doesn't know where to start the extraction for the following day or year field.

The atof(3) Function

The atof(3) function is very similar to the atoi(3) function, except that it converts string values into floating point values. The synopsis for atof(3) is as follows:

#include <stdlib.h>

double atof(const char *nptr);

Its use is equally simple. The following is an example:

char buf[32];
double f;

strcpy(buf,"  -467.01E+02");
f = atof(buf);

The example shows some leading whitespace, a sign character, a decimal number, and a signed exponent. The atof(3) function skips over the leading whitespace and converts the remaining characters into a double C type value, which is assigned to variable f.

Again, the simplicity of this call woos many a C programmer into using this form of conversion. However, the problems that exist for atoi(3) and atol(3) also apply to the atof(3) function.

Most UNIX platforms implement the atof(3) function as a call to the function strtod(3):

strtod(nptr, (char **)NULL);

The function strtod(3) does return the special values +HUGE_VAL, -HUGE_VAL, and 0 (zero), in conjunction with the external variable errno (see the section "Testing for Math Errors," later in this chapter). Since the implementation of atof(3) might not always be in terms of the strtod(3) function, you should use strtod(3) to test for errors.