strtol

STRTOL(3)                Руководство программиста Linux                STRTOL(3)



ИМЯ
       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», что означает использование шестнадцатеричной системы исчисления;
       иначе, если 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);
       }

СМОТРИТЕ ТАКЖЕ
       atof(3), atoi(3), atol(3), strtod(3), strtoul(3)



GNU                                2016-03-15                          STRTOL(3)