Целые числа

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

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

type PyLongObject

Часть Ограниченного API (в качестве неявного структуры).

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

PyTypeObject PyLong_Type

Часть Стабильного ABI.

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

int PyLong_Check(PyObject *p)

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

int PyLong_CheckExact(PyObject *p)

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

PyObject *PyLong_FromLong(long v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

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

PyObject *PyLong_FromUnsignedLong(unsigned long v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

PyObject *PyLong_FromSsize_t(Py_ssize_t v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

PyObject *PyLong_FromSize_t(size_t v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

PyObject *PyLong_FromLongLong(long long v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

PyObject *PyLong_FromDouble(double v)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

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

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

См. также

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

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)

Значение возврата: Новая ссылка.

Преобразуйте последовательность символов Unicode в строке u в значение целого числа Python.

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

PyObject *PyLong_FromVoidPtr(void *p)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

long PyLong_AsLong(PyObject *obj)

Часть Стабильного ABI.

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

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

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

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

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

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Часть Стабильного API.

Возвращает представление числа 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)

Часть Стабильного API.

Возвращает представление числа 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)

Часть Стабильного API.

Возвращает представление числа 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)

Часть Стабильного API.

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

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

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

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Часть Стабильного API.

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

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

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

size_t PyLong_AsSize_t(PyObject *pylong)

Часть Стабильного API.

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

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

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

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Часть Стабильного API.

Возвращает представление 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)

Часть Стабильного API.

Возвращает представление значения 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)

Часть Стабильного API.

Возвращает представление значения 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)

Часть Стабильного API.

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

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

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

void *PyLong_AsVoidPtr(PyObject *pylong)

Часть Стабильного API.

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

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

PyObject *PyLong_GetInfo(void)

Часть Стабильного API.

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

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

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

int PyUnstable_Long_IsCompact(const PyLongObject *op)

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

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

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

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

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

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

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

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

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