atoi, _atoi_l, _wtoi, _wtoi_l

Converta uma cadeia de caracteres em inteiro.

Sintaxe

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
);

Parâmetros

str
Cadeia de caracteres a ser convertida.

locale
Localidade a usar.

Valor retornado

Cada função retorna o valor int produzido interpretando os caracteres de entrada como um número. O valor retornado será 0 para atoi e _wtoi, se a entrada não puder ser convertida em um valor desse tipo.

Quando as funções transbordam com grandes valores integrais negativos, LONG_MIN é retornado. atoi e _wtoi retornam INT_MAX e INT_MIN nessas condições. Em todos os casos de fora do intervalo, errno é definido como ERANGE. Se o parâmetro passado for NULL, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão 0.

Comentários

Essas funções convertem uma cadeia de caracteres em um valor inteiro (atoi e _wtoi). A cadeia de caracteres de entrada é uma sequência de caracteres que pode ser interpretada como um valor numérico do tipo especificado. A função para de ler a cadeia de caracteres de entrada no primeiro caractere que não pode ser reconhecida como parte de um número. Esse caractere pode ser o caractere nulo ('\0' ou L'\0') que encerra a cadeia de caracteres.

O argumento str para atoi e _wtoi tem a seguinte forma:

[whitespace] [sign] [digits]

Um whitespace consiste em caracteres de espaço ou tabulação, que são ignorados; sign é um sinal de mais (+) ou menos (-); e digits é um ou mais dígitos.

As versões dessas funções com o sufixo _l são idênticas, com a exceção de que usam o parâmetro de localidade passado em vez da localidade atual. Para obter mais informações, consulte Localidade.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Requisitos

Exemplo

Esse programa mostra como os números armazenados como cadeias de caracteres podem ser convertidos em valores numéricos usando as funções atoi.

// 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 occurring.
    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.

Confira também

Conversão de dados
Suporte matemático e de ponto flutuante
Localidade
_ecvt
_fcvt
_gcvt
setlocale, _wsetlocale
_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, , _atoflt_l