atol、_atol_l、_wtol、_wtol_l

發行項
06/09/2015

將字串轉換成長整數。

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

參數

str
要轉換的字串。
locale
要使用的地區設定。

傳回值

每個函式會傳回將輸入字元解譯為數字所產生的 long 值。如果輸入無法轉換為該類型的值，atol 的傳回值為 0L。

在處理大型正整數值的溢位的情況下， atol 會傳回 LONG_MAX;在處理大型負整數值的溢位的情況下，則會傳回 LONG_MIN 。在所有超出範圍的情況下，errno 會設為 ERANGE。如果傳入的參數是 NULL，則會叫用無效的參數處理常式，如參數驗證中所述。如果允許繼續執行，這些函式會將 errno 設定為 EINVAL 並傳回 -0。

備註

這些函式會將字元字串轉換為長整數(atol)。

輸入字串是可解譯為指定類型的數值的字元序列。函式在遇到第一個無法辨識為數字一部分的字元時，會停止讀取輸入字串。這個字元可能是終止字串的NULL字元 ('\0' 或 L'\0')。

atol 的 str 引數有下列形式：

[whitespace] [sign] [digits]]

whitespace 包含空格或定位字元，這些字元會被忽略。sign 是加號 (+) 或減號 (–)；digits 是一個或多個數字。

_wtol 與 atol 相同，但是前者採用寬字元字串。

這些以 _l 後綴的函式版本除了使用傳入的地區設定以外行為相同。如需詳細資訊，請參閱地區設定。

一般文字常式對應

TCHAR.H 常式	_UNICODE &和 _MBCS 未定義	_MBCS 已定義	_UNICODE 已定義
_tstol	atol	atol	_wtol
_ttol	atol	atol	_wtol

需求

常式	必要的標頭
atol	<stdlib.h>
_atol_l, _wtol, _wtol_l	<stdlib.h> 以及 <wchar.h>

範例

這個程式會示範如何使用 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");
    }
}