atol, _atol_l, _wtol, _wtol_l

Convertir una cadena en un entero largo.

Sintaxis

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
Cadena que se va a convertir.

locale
Configuración regional que se va a usar.

Valor devuelto

Cada función devuelve el valor long que se genera al interpretar los caracteres de entrada como un número. El valor devuelto es 0L para atol si la entrada no se puede convertir en un valor de ese tipo.

Si estas funciones se desbordan con valores enteros positivos grandes, devuelven LONG_MAX. Si las funciones se desbordan con valores enteros negativos grandes, LONG_MIN se devuelve. En todos los casos de valores fuera del intervalo, errno se establece en ERANGE. Si el parámetro pasado en es NULL, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones establecen errno en EINVAL y devuelven 0.

Comentarios

Estas funciones convierten una cadena de caracteres en un valor entero largo (atol).

La cadena de entrada es una secuencia de caracteres que se puede interpretar como un valor numérico del tipo especificado. La función deja de leer la cadena de entrada en el primer carácter que no puede reconocer como parte de un número. Es posible que este carácter sea el carácter nulo (\0 or L\0) que termina la cadena.

El argumento str para atol tiene el formato siguiente:

[whitespace] [sign] [digits]

Un elemento whitespace consta de caracteres de espacio o tabulación, que se omiten; sign es más (+) o menos (-); y digits son uno o varios dígitos.

_wtol es idéntica a atol, salvo en que toma una cadena de caracteres anchos.

Las versiones de estas funciones con el sufijo _l son idénticas salvo que usan el parámetro locale pasado en lugar de la configuración regional actual. Para obtener más información, vea Locale.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tstol	atol	atol	_wtol
_ttol	atol	atol	_wtol

Requisitos

Rutinas	Encabezado necesario
atol	<stdlib.h>
_atol_l, _wtol, _wtol_l	<stdlib.h> y <wchar.h>

Ejemplo

Este programa muestra cómo se pueden convertir números almacenados como cadenas en valores numéricos con la función 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.

Consulte también

Conversión de datos
Compatibilidad con matemáticas y punto flotante
Configuración regional
_ecvt
_fcvt
_gcvt
setlocale, _wsetlocale
_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l