strtol, strtoll

long      strtol( const char*          str, char**          str_end, int base );

long      strtol( const char* restrict str, char** restrict str_end, int base );

long long strtoll( const char* restrict str, char** restrict str_end, int base );

Интерпретирует целочисленное значение в строке байтов, на которую указывает str.

Отбрасывает все пробельные символы (определяемые вызовом isspace), пока не будет найден первый непробельный символ, затем считывает максимально возможное количество символов, образующих допустимое представление целого числа с основанием n (где n=base), и преобразует их в целочисленное значение. Допустимое целочисленное значение состоит из следующих частей:

• (необязательно) знак плюс или минус
• (необязательно) префикс (0), обозначающий восьмеричное основание (применяется только если основание равно 8 или 0)
• (необязательно) префикс (0x или 0X), обозначающий шестнадцатеричное основание (применяется только если основание равно 16 или 0)
• последовательность цифр

Допустимые значения основания — {0, 2, 3, ..., 36}. Допустимые цифры для целых чисел с основанием 2 — {0, 1}, для целых чисел с основанием 3 — {0, 1, 2} и так далее. Для оснований больше 10 допустимые цифры включают буквы алфавита: от Aa для целого числа с основанием 11 до Zz для целого числа с основанием 36. Регистр символов не учитывается.

Текущая установленная локаль C может допускать дополнительные числовые форматы.

Если значение base равно 0, основание числа определяется автоматически: если префикс — 0, основание восьмеричное; если префикс — 0x или 0X, основание шестнадцатеричное; в противном случае основание десятичное.

Если во входной последовательности присутствовал знак минус, числовое значение, вычисленное по последовательности цифр, меняет знак, как если бы к нему применялась унарная операция отрицания в типе результата.

Функции устанавливают указатель, на который указывает str_end, так, чтобы он указывал на символ после последнего интерпретированного числового символа. Если str_end — нулевой указатель, он игнорируется.

Если str пуста или не имеет ожидаемого формата, преобразование не выполняется, и (если str_end не является нулевым указателем) значение str сохраняется в объекте, на который указывает str_end.

Параметры

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

• В случае успеха возвращается целочисленное значение, соответствующее содержимому str.
• Если преобразованное значение выходит за пределы диапазона соответствующего возвращаемого типа, возникает ошибка диапазона (при этом errno устанавливается в ERANGE) и возвращается LONG_MAX, LONG_MIN, LLONG_MAX или LLONG_MIN (в зависимости от знака значения и возвращаемого типа).
• Если преобразование выполнить невозможно, возвращается 0.

Пример

#include <errno.h>
#include <limits.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    // parsing with error handling
    const char* p = "10 200000000000000000000000000000 30 -40 junk";
    printf("Parsing '%s':\n", p);

    for (;;)
    {
        // errno can be set to any non-zero value by a library function call
        // regardless of whether there was an error, so it needs to be cleared
        // in order to check the error set by strtol
        errno = 0;
        char* end;
        const long i = strtol(p, &end, 10);
        if (p == end)
            break;
 
        const bool range_error = errno == ERANGE;
        printf("Extracted '%.*s', strtol returned %ld.", (int)(end-p), p, i);
        p = end;
 
        if (range_error)
            printf("\n --> Range error occurred.");
 
        putchar('\n');
    }
    
    printf("Unextracted leftover: '%s'\n\n", p);
 
    // parsing without error handling
    printf("\"1010\" in binary  --> %ld\n", strtol("1010", NULL, 2));
    printf("\"12\"   in octal   --> %ld\n", strtol("12",   NULL, 8));
    printf("\"A\"    in hex     --> %ld\n", strtol("A",    NULL, 16));
    printf("\"junk\" in base-36 --> %ld\n", strtol("junk", NULL, 36));
    printf("\"012\"  in auto-detected base --> %ld\n", strtol("012",  NULL, 0));
    printf("\"0xA\"  in auto-detected base --> %ld\n", strtol("0xA",  NULL, 0));
    printf("\"junk\" in auto-detected base --> %ld\n", strtol("junk", NULL, 0));
}

Parsing '10 200000000000000000000000000000 30 -40 junk':
Extracted '10', strtol returned 10.
Extracted ' 200000000000000000000000000000', strtol returned 9223372036854775807.
 --> Range error occurred.
Extracted ' 30', strtol returned 30.
Extracted ' -40', strtol returned -40.
Unextracted leftover: ' junk'

"1010" in binary  --> 10
"12"   in octal   --> 10
"A"    in hex     --> 10
"junk" in base-36 --> 926192
"012"  in auto-detected base --> 10
"0xA"  in auto-detected base --> 10
"junk" in auto-detected base --> 0

Ссылки

• Стандарт C23 (ISO/IEC 9899:2024):
• 7.24.1.7 Функции strtol, strtoll, strtoul и strtoull (стр. 362–363)
• Стандарт C17 (ISO/IEC 9899:2018):
• 7.22.1.4 Функции strtol, strtoll, strtoul и strtoull (стр. 251–252)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.22.1.4 Функции strtol, strtoll, strtoul и strtoull (стр. 344–345)
• Стандарт C99 (ISO/IEC 9899:1999):
• 7.20.1.4 Функции strtol, strtoll, strtoul и strtoull (стр. 310–311)
• Стандарт C89/C90 (ISO/IEC 9899:1990):
• 4.10.1.5 Функция strtol

См. также