HOWTO · C

Converter uma string para Inteiro em C

Este artigo introduz diferentes métodos em C para converter um string num número inteiro

Nesta página

Converter uma string C para um número inteiro depende dos dados que aceita e das verificações de que o seu programa precisa. A biblioteca padrão disponibiliza atoi(), strtol() e strtoumax(). Utilize atoi() apenas quando os dados de entrada forem fiáveis; se puderem estar malformados ou fora do intervalo do tipo de destino, prefira uma conversão com verificações, usando strtol() ou strtoumax().

Utilizar atoi() para converter uma string num número inteiro em C

atoi(), declarado em <stdlib.h>, ignora os espaços em branco iniciais, lê um sinal opcional e algarismos decimais e, em seguida, para no primeiro carácter que não faça parte do número. Devolve um int, mas a sua interface não indica onde a análise parou nem permite distinguir um zero válido de uma conversão falhada. Se o valor convertido não puder ser representado como int, o comportamento é indefinido. Utilize esta função apenas quando o formato e o intervalo dos dados de entrada estiverem garantidos por outros meios.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const char *input = "123";
    int value = atoi(input);
    printf("%s -> %d\n", input, value);
    return 0;
}

Saída observada:

123 -> 123

Utilizar strtol() para converter uma string num número inteiro em C

strtol() é declarado em <stdlib.h> e devolve um long. Aceita uma base entre 2 e 36: a base 10 lê números decimais, enquanto a base 0 reconhece os prefixos habituais dos números inteiros em C. Ignora os espaços em branco iniciais e para no primeiro carácter que não pertença ao número. Passe o endereço de um ponteiro final para determinar onde a análise parou. Se o ponteiro final continuar a apontar para o primeiro carácter da string, não foram convertidos algarismos; se apontar para um carácter diferente de nulo após a conversão, a string contém um sufixo.

Defina errno como zero antes de chamar strtol(). Se o resultado for igual a LONG_MIN ou LONG_MAX e errno == ERANGE, o valor estava fora do intervalo de long. Se o destino for int, verifique também se o valor está entre INT_MIN e INT_MAX antes de o converter. Este exemplo completo aceita apenas um valor decimal integral que caiba num int:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

#include <errno.h>
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const char *input = "123";
    char *end;
    errno = 0;
    long parsed = strtol(input, &end, 10);

    if (end == input || *end != '\0' || errno == ERANGE ||
        parsed < INT_MIN || parsed > INT_MAX) {
        puts("conversion failed");
        return 0;
    }

    printf("value=%d\n", (int)parsed);
    return 0;
}

Saída observada:

value=123

Em código de produção, decida se deve aceitar espaços em branco à volta do número ou um sufixo. A própria função strtol() permite espaços em branco iniciais, enquanto a verificação do ponteiro final acima rejeita qualquer sufixo após os algarismos. O resultado apresentado usa o rótulo inglês value, que permanece inalterado no exemplo.

Utilizar strtoumax() para converter uma string num número inteiro em C

strtoumax() é declarado em <inttypes.h> e converte para uintmax_t, o tipo inteiro sem sinal mais amplo disponibilizado pela implementação. Tal como strtol(), recebe um ponteiro final e uma base, e indica um excesso do intervalo através de errno == ERANGE, depois de errno ter sido reposto a zero. Inclua <stdint.h> para o tipo uintmax_t e <inttypes.h> para a função e a macro de formatação PRIuMAX.

Uma conversão sem sinal pode aceitar um sinal de menos inicial e produzir um resultado sem sinal de acordo com as regras da função. Se a aplicação exigir um valor não negativo, rejeite explicitamente o sinal de menos. O exemplo seguinte também exige pelo menos um algarismo, rejeita caracteres no final da string e apresenta o valor com a macro de formatação correspondente:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

#include <ctype.h>
#include <errno.h>
#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const char *input = "123";
    const char *sign = input;
    while (isspace((unsigned char)*sign)) {
        ++sign;
    }

    if (*sign == '-') {
        puts("conversion failed");
        return 0;
    }

    char *end;
    errno = 0;
    uintmax_t value = strtoumax(input, &end, 10);
    if (end == input || *end != '\0' || errno == ERANGE) {
        puts("conversion failed");
        return 0;
    }

    printf("value=%" PRIuMAX "\n", value);
    return 0;
}

Saída observada:

value=123

O tipo do resultado não tem sinal e pode ser mais amplo do que int; antes de o converter para um tipo mais estreito, compare o valor com o máximo desse tipo. O resultado apresentado usa o rótulo inglês value, que permanece inalterado no exemplo.

Escolher uma função C para converter strings em números inteiros

Escolha atoi() quando os dados de entrada forem fiáveis, couberem num int e o programa não precisar de distinguir dados malformados de um valor zero. Para dados do utilizador, ficheiros ou outras fontes que possam não respeitar o formato esperado, strtol() é geralmente a melhor opção para uma conversão com sinal, pois o ponteiro final e errno permitem validar o resultado. Verifique tanto o intervalo de long como o intervalo de qualquer tipo de destino mais estreito.

Escolha strtoumax() para uma quantidade não negativa que possa exceder o limite positivo de long. Confirme que foram consumidos algarismos, rejeite texto no final quando toda a string tiver de ser numérica, verifique ERANGE e aplique qualquer limite mais estreito definido pela aplicação. Nenhuma das funções com verificações determina o que a sua aplicação considera aceitável: quem chama a função tem de definir se permite espaços em branco, sinais, prefixos ou caracteres no final e, depois, validar essas regras antes de utilizar o resultado.