strtol, wcstol, _strtol_l, _wcstol_l

Статья
06/09/2015

Преобразует строки в целочисленное значение типа long.

long strtol(
   const char *nptr,
   char **endptr,
   int base 
);
long wcstol(
   const wchar_t *nptr,
   wchar_t **endptr,
   int base 
);
long _strtol_l(
   const char *nptr,
   char **endptr,
   int base,
   _locale_t locale
);
long _wcstol_l(
   const wchar_t *nptr,
   wchar_t **endptr,
   int base,
   _locale_t locale
);

Параметры

nptr
Строка, заканчивающаяся нулевым символом, для преобразования.
endptr
Указатель на символ, который останавливает сканирование.
base
Основание системы счисления, который следует использовать.
locale
Языковой стандарт, который необходимо использовать.

Возвращаемое значение

strtol возвращает значение, которое представлено в строке nptr, кроме случаев, когда представление вызвало бы переполнение; в этом случае возвращается значение LONG_MAX или LONG_MIN. strtol возвращает 0, если преобразование не может быть выполнено. wcstol возвращает значения аналогично strtol. Для обеих функций параметр errno имеет значение ERANGE, если переполнение или потеря точности происходит.

Дополнительные сведения об этих и других кодах ошибок см. в разделе _doserrno, errno, _sys_errlist и _sys_nerr.

Заметки

Функция strtol преобразовывает nptr в long. strtol прекращает чтение строки nptr на первом знаке, который она не может распознать как часть числа. Это может быть конечный символ null или первый числовой символ, который больше или равен base.

wcstol — это двухбайтовая версия strtol; её аргумент nptr — строка двухбайтовых символов. В остальном эти функции ведут себя идентично.

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_tcstol	strtol	strtol	wcstol
_tcstol_l	_strtol_l	_strtol_l	_wcstol_l

Параметр категории LC_NUMERIC текущего языкового стандарта определяет распознавание символа системы счисления в nptr*;* дополнительные сведения см. в разделе setlocale. Функции, не имеющие суффикса _l, используют текущий языковой стандарт; _strtol_l и _wcstol_l идентичны соответствующим функциям, которые не имеют суффикса _l, за исключением того, что они используют переданный им языковой стандарт. Для получения дополнительной информации см. Языковой стандарт.

Если endptr не равен NULL, то указатель на символ, из-за которого было прекращено сканирование, хранится в ячейке памяти, на которую указывает endptr. Если преобразование не может быть выполнено (допустимые цифры не были найдены, или было указано недопустимое основание), то значение nptr хранится в ячейке памяти, на которую указывает endptr.

strtol ожидает, что nptr указывает на строку следующей формы:

[whitespace] [{+ | –}] [0 [{ x | X }]] [digits]

whitespace может состоять из пробелов и символов табуляции, которые игнорируются. digits — одна или несколько десятичных цифр. Первый символ, который не удовлетворяет этой форме, прекращает сканирование. Если base от 2 до 36, то он используется как основание системы счисления. Если значение base равно 0, то начальные символы строки, указанной в nptr используются для идентификации базы. Если первый символ — "0", а второй символ не равен "x" или "X", строка интерпретируется как восьмеричное целое число. Если первый символ — «0», а второй символ не равен «x» или «x», строка интерпретируется как шестнадцатеричное целое число. Если первый символ от «1» до «9», строка интерпретируется как десятичное целое число. Буквы от «а» до «z» присваиваются значения от 10 до 35; разрешены только буквы с присвоенными значениями меньше base. Первый символ вне диапазона базы останавливает сканирование. Например, если base — 0 и первый сканированный символ — "0", то предполагается восьмеричное целое число и символ "8" или "9" остановит сканирование.