Целочисленные объекты

Все целые числа реализованы как «длинные» целочисленные объекты произвольного размера.

При ошибке большинство API PyLong_As* возвращают (return type)-1, которое невозможно отличить от числа. Используйте PyErr_Occurred() для устранения неоднозначности.

type PyLongObject

Часть Limited API (как непрозрачная структура).

Этот подтип PyObject представляет целочисленный объект Python.

PyTypeObject PyLong_Type

Часть Stable ABI.

Этот экземпляр PyTypeObject представляет целочисленный тип Python. Это тот же самый объект, что и int на уровне Python.

int PyLong_Check(PyObject *p)

Возвращает истину (true), если аргумент является PyLongObject или подтипом PyLongObject. Эта функция всегда завершается успешно.

int PyLong_CheckExact(PyObject *p)

Возвращает истину (true), если аргумент является PyLongObject, но не подтипом PyLongObject. Эта функция всегда завершается успешно.

PyObject *PyLong_FromLong(long v)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый объект PyLongObject из v или NULL в случае ошибки.

Текущая реализация хранит массив целочисленных объектов для всех целых чисел от -5 до 256. При создании int в этом диапазоне вы на самом деле просто получаете ссылку на существующий объект.

PyObject *PyLong_FromUnsignedLong(unsigned long v)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый объект PyLongObject из C unsigned long или NULL в случае ошибки.

PyObject *PyLong_FromSsize_t(Py_ssize_t v)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый объект PyLongObject из C Py_ssize_t или NULL в случае ошибки.

PyObject *PyLong_FromSize_t(size_t v)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый объект PyLongObject из C size_t или NULL в случае ошибки.

PyObject *PyLong_FromLongLong(long long v)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый объект PyLongObject из C long long или NULL в случае ошибки.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый объект PyLongObject из C unsigned long long или NULL в случае ошибки.

PyObject *PyLong_FromDouble(double v)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый объект PyLongObject из целочисленной части v или NULL в случае ошибки.

PyObject *PyLong_FromString(const char *str, char **pend, int base)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Возвращает новый PyLongObject на основе строкового значения в str, которое интерпретируется в соответствии с основанием системы счисления в base, или NULL в случае ошибки. Если pend не равен NULL, *pend будет указывать на конец str при успехе или на первый символ, который не удалось обработать, при ошибке. Если base равен 0, str интерпретируется в соответствии с определением Целочисленные литералы; в этом случае ведущие нули в ненулевом десятичном числе приводят к вызову ValueError. Если base не равен 0, он должен быть в диапазоне от 2 до 36 включительно. Начальные и конечные пробельные символы и одиночные символы подчеркивания после спецификатора основания и между цифрами игнорируются. Если цифры отсутствуют или str не завершается NULL после цифр и конечных пробельных символов, будет вызвано исключение ValueError.

См. также

Методы Python int.to_bytes() и int.from_bytes() для преобразования PyLongObject в массив байтов по основанию 256 и обратно. Их можно вызвать из C с помощью PyObject_CallMethod().

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)

Возвращаемое значение: Новая ссылка.

Преобразует последовательность цифр Юникода в строке u в целочисленное значение Python.

Добавлено в версии 3.3.

PyObject *PyLong_FromVoidPtr(void *p)

Возвращаемое значение: Новая ссылка. Часть Stable ABI.

Создает целое число Python из указателя p. Значение указателя можно извлечь из полученного значения с помощью PyLong_AsVoidPtr().

long PyLong_AsLong(PyObject *obj)

Часть Stable ABI.

Возвращает представление obj в виде C long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать его в PyLongObject.

Вызывает OverflowError, если значение obj выходит за пределы диапазона для long.

Возвращает -1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Используется __index__(), если доступно.

Изменено в версии 3.10: Эта функция больше не использует __int__().

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Часть Stable ABI.

Возвращает представление obj в виде C long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать его в PyLongObject.

Если значение obj больше LONG_MAX или меньше LONG_MIN, устанавливает *overflow в 1 или -1 соответственно и возвращает -1; в противном случае устанавливает *overflow в 0. При возникновении любого другого исключения устанавливает *overflow в 0 и возвращает -1, как обычно.

Возвращает -1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Используется __index__(), если доступно.

Изменено в версии 3.10: Эта функция больше не использует __int__().

long long PyLong_AsLongLong(PyObject *obj)

Часть Stable ABI.

Возвращает представление obj в виде C long long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать его в PyLongObject.

Вызывает OverflowError, если значение obj выходит за пределы диапазона для long long.

Возвращает -1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Используется __index__(), если доступно.

Изменено в версии 3.10: Эта функция больше не использует __int__().

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

Часть Stable ABI.

Возвращает представление obj в виде C long long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать его в PyLongObject.

Если значение obj больше LLONG_MAX или меньше LLONG_MIN, устанавливает *overflow в 1 или -1 соответственно и возвращает -1; в противном случае устанавливает *overflow в 0. При возникновении любого другого исключения устанавливает *overflow в 0 и возвращает -1, как обычно.

Возвращает -1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

Добавлено в версии 3.2.

Изменено в версии 3.8: Используется __index__(), если доступно.

Изменено в версии 3.10: Эта функция больше не использует __int__().

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

Часть Stable ABI.

Возвращает представление pylong в виде C Py_ssize_t. pylong должен быть экземпляром PyLongObject.

Вызывает OverflowError, если значение pylong выходит за пределы диапазона для Py_ssize_t.

Возвращает -1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Часть Stable ABI.

Возвращает представление pylong в виде C unsigned long. pylong должен быть экземпляром PyLongObject.

Вызывает OverflowError, если значение pylong выходит за пределы диапазона для unsigned long.

Возвращает (unsigned long)-1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

size_t PyLong_AsSize_t(PyObject *pylong)

Часть Stable ABI.

Возвращает представление pylong в виде C size_t. pylong должен быть экземпляром PyLongObject.

Вызывает OverflowError, если значение pylong выходит за пределы диапазона для size_t.

Возвращает (size_t)-1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Часть Stable ABI.

Возвращает представление pylong в виде C unsigned long long. pylong должен быть экземпляром PyLongObject.

Вызывает OverflowError, если значение pylong выходит за пределы диапазона для unsigned long long.

Возвращает (unsigned long long)-1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.1: Отрицательное значение pylong теперь вызывает OverflowError, а не TypeError.

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)

Часть Stable ABI.

Возвращает представление obj в виде C unsigned long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать его в PyLongObject.

Если значение obj выходит за пределы диапазона для unsigned long, возвращает остаток от деления этого значения по модулю ULONG_MAX + 1.

Возвращает (unsigned long)-1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Используется __index__(), если доступно.

Изменено в версии 3.10: Эта функция больше не использует __int__().

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)

Часть Stable ABI.

Возвращает представление obj в виде C unsigned long long. Если obj не является экземпляром PyLongObject, сначала вызывается его метод __index__() (если он есть), чтобы преобразовать его в PyLongObject.

Если значение obj выходит за пределы диапазона для unsigned long long, возвращает остаток от деления этого значения по модулю ULLONG_MAX + 1.

Возвращает (unsigned long long)-1 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

Изменено в версии 3.8: Используется __index__(), если доступно.

Изменено в версии 3.10: Эта функция больше не использует __int__().

double PyLong_AsDouble(PyObject *pylong)

Часть Stable ABI.

Возвращает представление pylong в виде C double. pylong должен быть экземпляром PyLongObject.

Вызывает OverflowError, если значение pylong выходит за пределы диапазона для double.

Возвращает -1.0 в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

void *PyLong_AsVoidPtr(PyObject *pylong)

Часть Stable ABI.

Преобразует целое число Python pylong в указатель C void. Если pylong не может быть преобразован, будет вызвано исключение OverflowError. Гарантируется получение пригодного к использованию указателя void только для значений, созданных с помощью PyLong_FromVoidPtr().

Возвращает NULL в случае ошибки. Используйте PyErr_Occurred() для устранения неоднозначности.

PyObject *PyLong_GetInfo(void)

Часть Stable ABI.

При успехе возвращает доступный только для чтения именованный кортеж, содержащий информацию о внутреннем представлении целых чисел в Python. См. описание отдельных полей в sys.int_info.

В случае ошибки возвращает NULL с установленным исключением.

Добавлено в версии 3.1.

int PyUnstable_Long_IsCompact(const PyLongObject *op)

Это Unstable API. Он может измениться без предупреждения в минорных релизах.

Возвращает 1, если op является компактным, и 0 в противном случае.

Эта функция позволяет коду, критичному к производительности, реализовать «быстрый путь» для малых целых чисел. Для компактных значений используйте PyUnstable_Long_CompactValue(); для остальных используйте функцию PyLong_As* или calling int.to_bytes().

Ожидается, что ускорение будет незначительным для большинства пользователей.

То, какие именно значения считаются компактными, является деталью реализации и может измениться.

Добавлено в версии 3.12.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

Это Unstable API. Он может измениться без предупреждения в минорных релизах.

Если op является компактным, как определено функцией PyUnstable_Long_IsCompact(), возвращает его значение.

В противном случае возвращаемое значение не определено.

Добавлено в версии 3.12.