atoi, _atoi_l, _wtoi, _wtoi_l

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

Convert a string to integer.

int atoi(  
   const char *str   
);  
int _wtoi(  
   const wchar_t *str   
);  
int _atoi_l(  
   const char *str,  
   _locale_t locale  
);  
int _wtoi_l(  
   const wchar_t *str,  
   _locale_t locale  
);  

Parameters

str
String to be converted.

locale
Locale to use.

Each function returns the int value produced by interpreting the input characters as a number. The return value is 0 for atoi and _wtoi, if the input cannot be converted to a value of that type.

In the case of overflow with large negative integral values, LONG_MIN is returned. atoi and _wtoi return INT_MAX and INT_MIN on these conditions. In all out-of-range cases, errno is set to ERANGE. If the parameter passed in is NULL, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, these functions set errno to EINVAL and return 0.

These functions convert a character string to an integer value (atoi and _wtoi). The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. The function stops reading the input string at the first character that it cannot recognize as part of a number. This character may be the null character ('\0' or L'\0') terminating the string.

The str argument to atoiand _wtoi has the following form:

[whitespace] [sign] [digits]]

A whitespace consists of space or tab characters, which are ignored; sign is either plus (+) or minus (–); and digits are one or more digits.

The versions of these functions with the _l suffix are identical except that they use the locale parameter passed in instead of the current locale. For more information, see Locale.

Generic-Text Routine Mappings

This program shows how numbers stored as strings can be converted to numeric values using the atoi functions.

// crt_atoi.c  
// This program shows how numbers   
// stored as strings can be converted to  
// numeric values using the atoi functions.  
  
#include <stdlib.h>  
#include <stdio.h>  
#include <errno.h>  
  
int main( void )  
{  
    char    *str = NULL;  
    int     value = 0;  
  
    // An example of the atoi function.  
    str = "  -2309 ";  
    value = atoi( str );  
    printf( "Function: atoi( \"%s\" ) = %d\n", str, value );  
  
    // Another example of the atoi function.  
    str = "31412764";  
    value = atoi( str );  
    printf( "Function: atoi( \"%s\" ) = %d\n", str, value );  
  
    // Another example of the atoi function   
    // with an overflow condition occuring.  
    str = "3336402735171707160320";  
    value = atoi( str );  
    printf( "Function: atoi( \"%s\" ) = %d\n", str, value );  
    if (errno == ERANGE)  
    {  
       printf("Overflow condition occurred.\n");  
    }  
}  

Function: atoi( "  -2309 " ) = -2309  
Function: atoi( "31412764" ) = 31412764  
Function: atoi( "3336402735171707160320" ) = 2147483647  
Overflow condition occurred.  

• System::Convert::ToInt32

• System::Convert::ToUInt32

Data Conversion
Floating-Point Support
Locale
_ecvt
_fcvt
_gcvt
setlocale, _wsetlocale
_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l