atol, _atol_l, _wtol, _wtol_l

Converte uma cadeia de caracteres em um inteiro longo.

Sintaxe

long atol(
   const char *str
);
long _atol_l(
   const char *str,
   _locale_t locale
);
long _wtol(
   const wchar_t *str
);
long _wtol_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 long produzido interpretando os caracteres de entrada como um número. O valor retornado é 0L para atol se a entrada não puder ser convertida em um valor desse tipo.

Se essas funções transbordarem com grandes valores integrais positivos, elas retornarão LONG_MAX. Se as funções estourarem com grandes valores integrais negativos, LONG_MIN será retornado. 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 longo (atol).

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 termina a cadeia de caracteres.

O argumento str para atol 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.

_wtol é idêntico a atol, exceto que assume uma cadeia de caracteres largos.

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 a função atol.

// crt_atol.c
// This program shows how numbers stored as
// strings can be converted to numeric values
// using the atol functions.
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>

int main( void )
{
    char    *str = NULL;
    long    value = 0;

    // An example of the atol function
    // with leading and trailing white spaces.
    str = "  -2309 ";
    value = atol( str );
    printf( "Function: atol( \"%s\" ) = %d\n", str, value );

    // Another example of the atol function
    // with an arbitrary decimal point.
    str = "314127.64";
    value = atol( str );
    printf( "Function: atol( \"%s\" ) = %d\n", str, value );

    // Another example of the atol function
    // with an overflow condition occurring.
    str = "3336402735171707160320";
    value = atol( str );
    printf( "Function: atol( \"%s\" ) = %d\n", str, value );
    if (errno == ERANGE)
    {
       printf("Overflow condition occurred.\n");
    }
}

Function: atol( "  -2309 " ) = -2309
Function: atol( "314127.64" ) = 314127
Function: atol( "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