atol, _atol_l, _wtol, _wtol_l

Artigo
06/09/2015

Converter uma cadeia de caracteres em um inteiro.

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 ser usada.

Valor de retorno

Cada função retorna o valor de long gerado interpretando os caracteres de entrada como um número. O valor de retorno é 0L para atol se a entrada não pode ser convertida em um valor desse tipo.

No caso de estouro integrais com grandes valores positivos, atol retorna LONG_MAX; no caso de estouro integrais com grandes valores negativos, LONG_MIN é retornado. Em todos os casos fora do intervalo, errno será definido como ERANGE. Se o parâmetro passado for NULL, o manipulador inválido do parâmetro será chamado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções definirão errno para EINVAL e retornarão 0.

Comentários

Essas funções convertem uma cadeia de caracteres a um valor inteiro longo (atol).

A cadeia de caracteres de entrada é uma sequência de caracteres que pode ser interpretados como um valor numérico do tipo especificado. A função deixa de ler a cadeia de caracteres de entrada no primeiro caractere que ela não reconhece ser parte de um número. Esse caractere pode ser o caractere de NULL (“\ 0 " ou L \ 0 ') que encerra a cadeia de caracteres.

O argumento str para atol tem o seguinte formato:

[whitespace] [sign] [digits]]

Um whitespace consiste no espaço ou em caracteres da guia, que são ignorados; sign é mais (+) ou menos (–); e digits é um ou mais dígitos.

_wtol é idêntico a atol exceto que usa uma cadeia de caracteres amplas.

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

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tstol	atol	atol	_wtol
_ttol	atol	atol	_wtol

Requisitos

Rotinas	Cabeçalho necessário
atol	<stdlib.h>
_atol_l, _wtol, _wtol_l	<stdlib.h e> wchar.h <>

Exemplo

Esse programa mostra como os números armazenados como cadeias de caracteres poderão ser convertidos em valores numéricos usando a função de 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");
    }
}