ИМЯ

strtol, strtoll, strtoq - преобразует строку в длинное целое число

ОБЗОР

#include <stdlib.h>

long int strtol(const char *nptr, char **endptr, int base);

long long int strtoll(const char *nptr, char **endptr, int base);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

strtoll():

_ISOC99_SOURCE || /* в версии glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

ОПИСАНИЕ

Функция strtol() преобразует начальную часть строки nptr в длинное целое число согласно системе счисления base, значение которой может быть от 2 до 36 включительно или равно специальному значению 0.

Строка может начинаться с произвольного количества пробельных символов (определяемых при помощи isspace(3)), затем может быть указан знак «+» или «-». Если base равно 0 или 16, то строка может начинаться с приставки «0x» или «0X», что означает использование шестнадцатеричной системы исчисления; иначе, если base равно нулю, то используется десятичная система счисления (кроме, когда последующий символ также равен «0»: в этом случае используется восьмеричная система исчисления).

Остаток строки преобразуется в число с типом long int. Этот процесс останавливается, если в строке встречается некорректный символ для указанной системе счисления. В системах счисления больших 10, символ «A» в верхнем или нижнем регистре означает 10, «B» означает 11 и так далее до «Z», означающего 35.

Если значение endptr не NULL, то strtol() записывает адрес первого некорректного символа в *endptr. Если в строке вообще нет цифр, то strtoul() сохраняет изначальное значение nptr в *endptr (и возвращает 0). В частности, если *nptr не равно '\0', но **endptr равно '\0' при возврате, то вся строка состоит из корректных символов.

Функция strtoll() работает так же, как и strtol(), но возвращает число с типом long long int.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Функция strtol() возвращает результат преобразования, если значение не возникают переполнения или исчерпания. Если возникает исчерпание, то strtol() возвращает LONG_MIN. Если возникает переполнение, то strtoul() возвращает LONG_MAX. В обоих случаях переменной errno присваивается значение ERANGE. То же самое относится к strtoll(), только вместо LONG_MIN и LONG_MAX возвращается LLONG_MIN и LLONG_MAX.

ОШИБКИ

EINVAL: (нет в C99) Аргумент base содержит неподдерживаемое значение.
ERANGE: Полученное значение вне диапазона.

Реализация может также устанавливать errno в EINVAL в случае, когда преобразование не было выполнено (не было встречено цифр и возвращён 0).

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
strtol(), strtoll(), strtoq()	Безвредность в нитях	MT-Safe locale

СООТВЕТСТВИЕ СТАНДАРТАМ

strtol(): POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD.

strtoll(): POSIX.1-2001, POSIX.1-2008, C99.

ЗАМЕЧАНИЯ

Так как strtol() может обоснованно вернуть 0, LONG_MAX или LONG_MIN (а strtoll() — LLONG_MAX или LLONG_MIN) при успешном выполнении и ошибке, вызывающая программа до вызова должна присвоить errno значение 0, а после вызова определить возникновение ошибки по ненулевому значению errno.

Согласно POSIX.1, в локалях отличных от «C» и «POSIX», эти функции могут преобразовывать другие, определяемые реализацией, строки с числами.

В BSD также есть функция

quad_t strtoq(const char *nptr, char **endptr, int base);

с полностью аналогичным определением. В зависимости от длины слова в текущей архитектуре, она может быть аналогом strtoll() или strtol().

ПРИМЕР

Программа, представленная далее, показывает использование strtol(). В первом аргументе командной строки указывается срока, из которой strtol() должна извлечь число. Во втором (необязательном) аргументе указывается система счисления, используемая для преобразования (этот аргумент преобразуется в число с помощью atoi(3), функции, которая не учитывает ошибки и имеет более простой интерфейс по сравнению с strtol()). Вот несколько результатов работы этой программы:

$ ./a.out 123
strtol() вернула 123
$ ./a.out '    123'
strtol() вернула 123
$ ./a.out 123abc
strtol() вернула 123
Остальные символы после числа: abc
$ ./a.out 123abc 55
strtol: некорректный аргумент
$ ./a.out ''
Цифры отсутствуют
$ ./a.out 4000000000
strtol: Числовой результат выходит за диапазон

Исходный код программы

#include <stdlib.h>
#include <limits.h>
#include <stdio.h>
#include <errno.h>
int
main(int argc, char *argv[])
{

    int base;

    char *endptr, *str;

    long val;

    if (argc < 2) {

        fprintf(stderr, "Использование: %s строка [система_счисления]\n", argv[0]);

        exit(EXIT_FAILURE);

    }

    str = argv[1];

    base = (argc > 2) ? atoi(argv[2]) : 10;

    errno = 0;    /* чтобы выявить ошибку после вызова */

    val = strtol(str, &endptr, base);

    /* проверка возможных ошибок */

    if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN))

            || (errno != 0 && val == 0)) {

        perror("strtol");

        exit(EXIT_FAILURE);

    }

    if (endptr == str) {

        fprintf(stderr, "Цифры отсутствуют\n");

        exit(EXIT_FAILURE);

    }

    /* если мы дошли сюда, то strtol() успешно преобразовала число */

    printf("strtol() вернула %ld\n", val);

    if (*endptr != '\0')        /* необязательно ошибка… */

        printf("Остальные символы после числа: %s\n", endptr);

    exit(EXIT_SUCCESS);
}

ИМЯ