`long.md`

264 строк · 21.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.10/c-api/long.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Целочисленные объекты89Все целые числа реализованы как «длинные» целочисленные объекты произвольного размера.1011При ошибке большинство API `PyLong_As*` возвращают `(return type)-1`, который невозможно отличить от числа. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.1213#### `type PyLongObject`1415*Часть [Limited API](https://python-all.ru/3.10/c-api/stable.html#stable) (как непрозрачная структура).*1617Этот подтип [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject) представляет целочисленный объект Python.1819#### `PyTypeObject PyLong_Type`2021*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*2223Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.10/c-api/type.html#c.PyTypeObject) представляет целочисленный тип Python. Это тот же объект, что и [`int`](https://python-all.ru/3.10/library/functions.html#int) на уровне Python.2425#### `int PyLong_Check(PyObject *p)`2627Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) или подтипом [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject). Эта функция всегда завершается успешно.2829#### `int PyLong_CheckExact(PyObject *p)`3031Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject), но не подтипом [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject). Эта функция всегда завершается успешно.3233#### `PyObject *PyLong_FromLong(long v)`3435*Возвращаемое значение: новая ссылка.*3637*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*3839Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) из *v* или `NULL` при ошибке.4041Текущая реализация хранит массив целочисленных объектов для всех целых чисел от `-5` до `256`. Когда создаётся целое число из этого диапазона, фактически возвращается ссылка на уже существующий объект.4243#### `PyObject *PyLong_FromUnsignedLong(unsigned long v)`4445*Возвращаемое значение: новая ссылка.*4647*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*4849Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) из C `unsigned long` или `NULL` при ошибке.5051#### `PyObject *PyLong_FromSsize_t(Py_ssize_t v)`5253*Возвращаемое значение: новая ссылка.*5455*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*5657Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) из C [`Py_ssize_t`](https://python-all.ru/3.10/c-api/intro.html#c.Py_ssize_t) или `NULL` при ошибке.5859#### `PyObject *PyLong_FromSize_t(size_t v)`6061*Возвращаемое значение: новая ссылка.*6263*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*6465Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) из C `size_t` или `NULL` при ошибке.6667#### `PyObject *PyLong_FromLongLong(long long v)`6869*Возвращаемое значение: новая ссылка.*7071*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*7273Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) из C `long long` или `NULL` при ошибке.7475#### `PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)`7677*Возвращаемое значение: новая ссылка.*7879*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*8081Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) из C `unsigned long long`, или `NULL` при ошибке.8283#### `PyObject *PyLong_FromDouble(double v)`8485*Возвращаемое значение: новая ссылка.*8687*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*8889Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) из целой части *v* или `NULL` в случае ошибки.9091#### `PyObject *PyLong_FromString(const char *str, char **pend, int base)`9293*Возвращаемое значение: новая ссылка.*9495*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*9697Возвращает новый [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) на основе строки *str*, которая интерпретируется в соответствии с основанием системы счисления *base*. Если *pend* не равно `NULL`, *\*pend* будет указывать на первый символ в *str*, следующий за представлением числа. Если *base* равно `0`, то *str* интерпретируется с помощью определения [целочисленных литералов](https://python-all.ru/3.10/reference/lexical_analysis.html#integers); в этом случае ведущие нули в ненулевом десятичном числе вызывают [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError). Если *base* не равно `0`, оно должно быть в диапазоне от `2` до `36` включительно. Ведущие пробелы и одиночные символы подчёркивания после указателя основания и между цифрами игнорируются. Если цифры отсутствуют, возникает [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError).9899> **См. также**100>101> Методы Python [`int.to_bytes()`](https://python-all.ru/3.10/library/stdtypes.html#int.to_bytes) и [`int.from_bytes()`](https://python-all.ru/3.10/library/stdtypes.html#int.from_bytes) для преобразования [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject) в массив байтов по основанию `256` и обратно. Эти методы можно вызывать из C с помощью [`PyObject_CallMethod()`](https://python-all.ru/3.10/c-api/call.html#c.PyObject_CallMethod).102103#### `PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)`104105*Возвращаемое значение: новая ссылка.*106107Преобразует последовательность цифр Unicode в строке *u* в целое число Python.108109Новое в версии 3.3.110111#### `PyObject *PyLong_FromVoidPtr(void *p)`112113*Возвращаемое значение: новая ссылка.*114115*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*116117Создаёт целое число Python из указателя *p*. Значение указателя можно извлечь из полученного значения с помощью [`PyLong_AsVoidPtr()`](https://python-all.ru/3.10/c-api/long.html#c.PyLong_AsVoidPtr).118119#### `long PyLong_AsLong(PyObject *obj)`120121*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*122123Возвращает C-представление `long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject), сначала вызывается его метод `__index__()` (если он есть), чтобы преобразовать его в [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).124125Возбуждает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для `long`.126127При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.128129Изменено в версии 3.8: Используйте `__index__()`, если доступно.130131Изменено в версии 3.10: Эта функция больше не использует `__int__()`.132133#### `long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)`134135*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*136137Возвращает C-представление `long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject), сначала вызывается его метод `__index__()` (если он есть), чтобы преобразовать его в [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).138139Если значение *obj* больше `LONG_MAX` или меньше `LONG_MIN`, установите *\*overflow* в `1` или `-1` соответственно и верните `-1`; в противном случае установите *\*overflow* в `0`. Если возникает любое другое исключение, установите *\*overflow* в `0` и верните `-1` как обычно.140141При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.142143Изменено в версии 3.8: Используйте `__index__()`, если доступно.144145Изменено в версии 3.10: Эта функция больше не использует `__int__()`.146147#### `long long PyLong_AsLongLong(PyObject *obj)`148149*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*150151Возвращает C-представление `long long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject), сначала вызывается его метод `__index__()` (если он есть), чтобы преобразовать его в [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).152153Возбуждает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для `long long`.154155При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.156157Изменено в версии 3.8: Используйте `__index__()`, если доступно.158159Изменено в версии 3.10: Эта функция больше не использует `__int__()`.160161#### `long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)`162163*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*164165Возвращает C-представление `long long` объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject), сначала вызывается его метод `__index__()` (если он есть), чтобы преобразовать его в [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).166167Если значение *obj* больше `LLONG_MAX` или меньше `LLONG_MIN`, устанавливает *\*overflow* в `1` или `-1` соответственно и возвращает `-1`; в противном случае устанавливает *\*overflow* в `0`. Если возникает любое другое исключение, устанавливает *\*overflow* в `0` и возвращает `-1` как обычно.168169При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.170171Новое в версии 3.2.172173Изменено в версии 3.8: Используйте `__index__()`, если доступно.174175Изменено в версии 3.10: Эта функция больше не использует `__int__()`.176177#### `Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)`178179*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*180181Возвращает C-представление [`Py_ssize_t`](https://python-all.ru/3.10/c-api/intro.html#c.Py_ssize_t) объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).182183Вызывает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для [`Py_ssize_t`](https://python-all.ru/3.10/c-api/intro.html#c.Py_ssize_t).184185При ошибке возвращает `-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.186187#### `unsigned long PyLong_AsUnsignedLong(PyObject *pylong)`188189*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*190191Возвращает C-представление `unsigned long` для *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).192193Вызывает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `unsigned long`.194195Возвращает `(unsigned long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred).196197#### `size_t PyLong_AsSize_t(PyObject *pylong)`198199*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*200201Возвращает C-представление `size_t` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).202203Вызывает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `size_t`.204205Возвращает `(size_t)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred).206207#### `unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)`208209*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*210211Возвращает C-представление `unsigned long long` для *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).212213Возбуждает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы допустимого диапазона для `unsigned long long`.214215Возвращает `(unsigned long long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred).216217Изменено в версии 3.1: Отрицательное значение *pylong* теперь вызывает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), а не [`TypeError`](https://python-all.ru/3.10/library/exceptions.html#TypeError).218219#### `unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)`220221*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*222223Возвращает представление *obj* в виде C `unsigned long`. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject), сначала вызывается его метод `__index__()` (если он есть), чтобы преобразовать его в [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).224225Если значение *obj* выходит за пределы допустимого диапазона для `unsigned long`, возвращается приведение этого значения по модулю `ULONG_MAX + 1`.226227При ошибке возвращает `(unsigned long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.228229Изменено в версии 3.8: Используйте `__index__()`, если доступно.230231Изменено в версии 3.10: Эта функция больше не использует `__int__()`.232233#### `unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)`234235*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*236237Возвращает представление *obj* в виде C `unsigned long long`. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject), сначала вызывается его метод `__index__()` (если он есть), чтобы преобразовать его в [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).238239Если значение *obj* выходит за пределы допустимого диапазона для `unsigned long long`, возвращается приведение этого значения по модулю `ULLONG_MAX + 1`.240241При ошибке возвращает `(unsigned long long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.242243Изменено в версии 3.8: Используйте `__index__()`, если доступно.244245Изменено в версии 3.10: Эта функция больше не использует `__int__()`.246247#### `double PyLong_AsDouble(PyObject *pylong)`248249*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*250251Возвращает C-представление `double` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.10/c-api/long.html#c.PyLongObject).252253Вызывает [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `double`.254255При ошибке возвращает `-1.0`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.256257#### `void *PyLong_AsVoidPtr(PyObject *pylong)`258259*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*260261Преобразует целое число Python *pylong* в C-указатель `void`. Если *pylong* не удаётся преобразовать, возбуждается [`OverflowError`](https://python-all.ru/3.10/library/exceptions.html#OverflowError). Гарантированно получается пригодный для использования указатель `void` только для значений, созданных с помощью [`PyLong_FromVoidPtr()`](https://python-all.ru/3.10/c-api/long.html#c.PyLong_FromVoidPtr).262263При ошибке возвращает `NULL`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.10/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.264