`long.md`

716 строк · 56.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/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.16/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.1213#### `type PyLongObject`1415*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) (как непрозрачная структура).*1617Этот подтип [`PyObject`](https://python-all.ru/3.16/c-api/structures.html#c.PyObject) представляет целочисленный объект Python.1819#### `PyTypeObject PyLong_Type`2021*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*2223Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject) представляет целочисленный тип Python. Это тот же объект, что и [`int`](https://python-all.ru/3.16/library/functions.html#int) на уровне Python.2425#### `int PyLong_Check(PyObject *p)`2627Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) или подтипом `PyLongObject`. Эта функция всегда завершается успешно.2829#### `int PyLong_CheckExact(PyObject *p)`3031Возвращает истину, если аргумент является [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), но не подтипом `PyLongObject`. Эта функция всегда завершается успешно.3233#### `PyObject *PyLong_FromLong(long v)`3435*Возвращаемое значение: новая ссылка.*3637*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*3839Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) из *v* или `NULL` при ошибке.4041**Деталь реализации CPython:** CPython хранит массив целочисленных объектов для всех целых чисел в диапазоне от `-5` до `1024`. При создании int в этом диапазоне фактически возвращается ссылка на существующий объект.4243#### `PyObject *PyLong_FromUnsignedLong(unsigned long v)`4445*Возвращаемое значение: новая ссылка.*4647*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*4849Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/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.16/c-api/stable.html#stable).*5657Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) из C [`Py_ssize_t`](https://python-all.ru/3.16/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.16/c-api/stable.html#stable).*6465Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/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.16/c-api/stable.html#stable).*7273Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/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.16/c-api/stable.html#stable).*8081Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) из C unsigned long long или `NULL` при ошибке.8283#### `PyObject *PyLong_FromInt32(int32_t value)`8485#### `PyObject *PyLong_FromInt64(int64_t value)`8687*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*8889Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) из знакового C int32\_t или int64\_t, или `NULL` с установленным исключением при ошибке.9091Добавлено в версии 3.14.9293#### `PyObject *PyLong_FromUInt32(uint32_t value)`9495#### `PyObject *PyLong_FromUInt64(uint64_t value)`9697*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*9899Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) из беззнакового C uint32\_t или uint64\_t, или `NULL` с установленным исключением при ошибке.100101Добавлено в версии 3.14.102103#### `PyObject *PyLong_FromDouble(double v)`104105*Возвращаемое значение: новая ссылка.*106107*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*108109Возвращает новый объект [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) из целой части *v* или `NULL` в случае ошибки.110111#### `PyObject *PyLong_FromString(const char *str, char **pend, int base)`112113*Возвращаемое значение: новая ссылка.*114115*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*116117Возвращает новый [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) на основе строкового значения *str*, которое интерпретируется в соответствии с основанием *base*, или `NULL` в случае ошибки. Если *pend* не `NULL`, то *\*pend* будет указывать на конец *str* в случае успеха или на первый символ, который не удалось обработать, в случае ошибки. Если *base* равно `0`, то *str* интерпретируется в соответствии с определением [Integer literals](https://python-all.ru/3.16/reference/lexical_analysis.html#integers); в этом случае ведущие нули в ненулевом десятичном числе вызывают [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError). Если *base* не равно `0`, оно должно быть между `2` и `36` включительно. Начальные и конечные пробелы, а также одиночные символы подчёркивания после спецификатора основания и между цифрами игнорируются. Если цифр нет или *str* не завершается нулевым символом после цифр и конечных пробелов, будет вызвано `ValueError`.118119> **См. также**120>121> Функции [`PyLong_AsNativeBytes()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsNativeBytes) и [`PyLong_FromNativeBytes()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FromNativeBytes) можно использовать для преобразования [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) в массив байтов и обратно в системе счисления `256`.122123#### `PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)`124125*Возвращаемое значение: новая ссылка.*126127Преобразует последовательность цифр Unicode в строке *u* в целое число Python.128129Добавлено в версии 3.3.130131#### `PyObject *PyLong_FromVoidPtr(void *p)`132133*Возвращаемое значение: новая ссылка.*134135*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*136137Создаёт целое число Python из указателя *p*. Значение указателя можно извлечь из полученного значения с помощью [`PyLong_AsVoidPtr()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsVoidPtr).138139#### `PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)`140141*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*142143Создаёт целое число Python из значения, содержащегося в первых *n\_bytes* буфера *buffer*, интерпретируемого как знаковое число в дополнительном коде.144145*flags* – как для [`PyLong_AsNativeBytes()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsNativeBytes). Передача `-1` выберет нативный порядок байтов, используемый CPython, и будет считать, что старший бит является знаковым. Передача `Py_ASNATIVEBYTES_UNSIGNED_BUFFER` даёт тот же результат, что и вызов [`PyLong_FromUnsignedNativeBytes()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FromUnsignedNativeBytes). Остальные флаги игнорируются.146147Добавлено в версии 3.13.148149#### `PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)`150151*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*152153Создаёт целое число Python из значения, содержащегося в первых *n\_bytes* буфера *buffer*, интерпретируемого как беззнаковое число.154155*flags* – как для [`PyLong_AsNativeBytes()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsNativeBytes). Передача `-1` выберет нативный порядок байтов, используемый CPython, и будет считать, что старший бит не является знаковым. Флаги, не связанные с порядком байтов, игнорируются.156157Добавлено в версии 3.13.158159#### `PyLong_FromPid(pid)`160161Макрос для создания целого числа Python из идентификатора процесса.162163Может быть определён как псевдоним [`PyLong_FromLong()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FromLong) или [`PyLong_FromLongLong()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FromLongLong) в зависимости от размера типа PID в системе.164165Добавлено в версии 3.2.166167#### `long PyLong_AsLong(PyObject *obj)`168169*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*170171Возвращает представление на C long для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он присутствует) для преобразования в `PyLongObject`.172173Вызывает [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для long.174175Возвращает `-1` в случае ошибки. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred) для устранения неоднозначности.176177Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__), если доступно.178179Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__int__).180181#### `long PyLong_AS_LONG(PyObject *obj)`182183Полностью эквивалентна предпочтительной `PyLong_AsLong`. В частности, может завершиться ошибкой с [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError) или другим исключением.184185[Soft deprecated](https://python-all.ru/3.16/glossary.html#term-soft-deprecated) since version 3.14.186187#### `int PyLong_AsInt(PyObject *obj)`188189*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable), начиная с версии 3.13.*190191Аналогична [`PyLong_AsLong()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsLong), но сохраняет результат в C int вместо C long.192193Добавлено в версии 3.13.194195#### `long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)`196197*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*198199Возвращает представление на C long для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он присутствует) для преобразования в `PyLongObject`.200201Если значение *obj* больше `LONG_MAX` или меньше `LONG_MIN`, установите *\*overflow* в `1` или `-1` соответственно и верните `-1`; в противном случае установите *\*overflow* в `0`. Если возникает любое другое исключение, установите *\*overflow* в `0` и верните `-1` как обычно.202203Возвращает `-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).204205Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__), если доступно.206207Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__int__).208209#### `long long PyLong_AsLongLong(PyObject *obj)`210211*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*212213Возвращает C-представление long long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.214215Вызывает [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), если значение *obj* выходит за пределы допустимого диапазона для long long.216217Возвращает `-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).218219Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__), если доступно.220221Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__int__).222223#### `long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)`224225*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*226227Возвращает C-представление long long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.228229Если значение *obj* больше `LLONG_MAX` или меньше `LLONG_MIN`, устанавливает *\*overflow* в `1` или `-1` соответственно и возвращает `-1`; в противном случае устанавливает *\*overflow* в `0`. Если возникает любое другое исключение, устанавливает *\*overflow* в `0` и возвращает `-1` как обычно.230231Возвращает `-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).232233Добавлено в версии 3.2.234235Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__), если доступно.236237Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__int__).238239#### `Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)`240241*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*242243Возвращает C-представление [`Py_ssize_t`](https://python-all.ru/3.16/c-api/intro.html#c.Py_ssize_t) объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject).244245Вызывает [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для [`Py_ssize_t`](https://python-all.ru/3.16/c-api/intro.html#c.Py_ssize_t).246247Возвращает `-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).248249#### `unsigned long PyLong_AsUnsignedLong(PyObject *pylong)`250251*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*252253Возвращает C-представление unsigned long объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject).254255Вызывает [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для unsigned long.256257Возвращает `(unsigned long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).258259#### `size_t PyLong_AsSize_t(PyObject *pylong)`260261*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*262263Возвращает C-представление `size_t` объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject).264265Вызывает [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для `size_t`.266267Возвращает `(size_t)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).268269#### `unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)`270271*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*272273Возвращает C-представление unsigned long long объекта *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject).274275Вызывает [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для unsigned long long.276277Возвращает `(unsigned long long)-1` в случае ошибки. Для устранения неоднозначности используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred).278279Изменено в версии 3.1: Отрицательное значение *pylong* теперь вызывает [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), а не [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError).280281#### `unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)`282283*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*284285Возвращает C-представление unsigned long объекта *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.286287Если значение *obj* выходит за пределы диапазона для unsigned long, возвращается приведение этого значения по модулю `ULONG_MAX + 1`.288289При ошибке возвращает `(unsigned long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.290291Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__), если доступно.292293Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__int__).294295#### `unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)`296297*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*298299Возвращает представление unsigned long long на языке C для *obj*. Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.300301Если значение *obj* выходит за пределы диапазона для unsigned long long, возвращается приведение этого значения по модулю `ULLONG_MAX + 1`.302303При ошибке возвращает `(unsigned long long)-1`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.304305Изменено в версии 3.8: Используйте [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__), если доступно.306307Изменено в версии 3.10: Эта функция больше не использует [`__int__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__int__).308309#### `int PyLong_AsInt32(PyObject *obj, int32_t *value)`310311#### `int PyLong_AsInt64(PyObject *obj, int64_t *value)`312313*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*314315Присваивает *\*value* знаковое представление int32\_t или int64\_t на языке C для *obj*.316317Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.318319Если значение *obj* выходит за пределы диапазона, возбуждается исключение [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError).320321Присваивает значение *\*value* и возвращает `0` при успехе. Возбуждает исключение и возвращает `-1` при ошибке.322323*value* не должен быть `NULL`.324325Добавлено в версии 3.14.326327#### `int PyLong_AsUInt32(PyObject *obj, uint32_t *value)`328329#### `int PyLong_AsUInt64(PyObject *obj, uint64_t *value)`330331*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*332333Присваивает *\*value* беззнаковое представление uint32\_t или uint64\_t на языке C для *obj*.334335Если *obj* не является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject), сначала вызывается его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__) (если он есть) для преобразования в `PyLongObject`.336337- Если *obj* отрицательное, возбуждается исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError).338- Если значение *obj* выходит за пределы диапазона, возбуждается исключение [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError).339340Присваивает значение *\*value* и возвращает `0` при успехе. Возбуждает исключение и возвращает `-1` при ошибке.341342*value* не должен быть `NULL`.343344Добавлено в версии 3.14.345346#### `double PyLong_AsDouble(PyObject *pylong)`347348*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*349350Возвращает представление double на языке C для *pylong*. *pylong* должен быть экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject).351352Возбуждает исключение [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError), если значение *pylong* выходит за пределы диапазона для double.353354При ошибке возвращает `-1.0`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.355356#### `void *PyLong_AsVoidPtr(PyObject *pylong)`357358*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*359360Преобразует целое число Python *pylong* в указатель void на языке C. Если *pylong* не удаётся преобразовать, возбуждается исключение [`OverflowError`](https://python-all.ru/3.16/library/exceptions.html#OverflowError). Это гарантирует, что полученный указатель void будет пригоден для использования только для значений, созданных с помощью [`PyLong_FromVoidPtr()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FromVoidPtr).361362При ошибке возвращает `NULL`. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred) для разрешения неоднозначности.363364#### `Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)`365366*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*367368Копирует значение целого числа Python *pylong* в нативный *buffer* размера *n\_bytes*. Флаг *flags* можно установить в `-1` для поведения, аналогичного приведению в C, или в значения, описанные ниже, для управления поведением.369370Возвращает `-1` с возбуждением исключения при ошибке. Это может произойти, если *pylong* не удаётся интерпретировать как целое число, или если *pylong* было отрицательным и был установлен флаг `Py_ASNATIVEBYTES_REJECT_NEGATIVE`.371372В противном случае возвращает количество байт, необходимое для хранения значения. Если оно меньше или равно *n\_bytes*, значение было скопировано целиком. Заполняются все *n\_bytes* буфера: оставшиеся байты заполняются копиями знакового бита.373374Если возвращённое значение больше *n\_bytes*, значение было усечено: записывается столько младших битов значения, сколько помещается, а старшие биты игнорируются. Это соответствует типичному поведению нисходящего приведения в стиле C.375376> **Примечание**377>378> Переполнение не считается ошибкой. Если возвращённое значение больше *n\_bytes*, старшие биты были отброшены.379380`0` никогда не будет возвращён.381382Значения всегда копируются в дополнительном коде.383384Пример использования:385386```c387int32_t value;388Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);389if (bytes < 0) {390    // Не удалось. Установлено исключение Python с указанием причины.391    return NULL;392}393else if (bytes <= (Py_ssize_t)sizeof(value)) {394    // Успешно!395}396else {397    // Произошло переполнение, но 'value' содержит усечённые398    // младшие биты pylong.399}400```401402Передача нуля в *n\_bytes* возвращает размер буфера, которого будет достаточно для хранения значения. Он может быть больше, чем технически необходимо, но не чрезмерно. Если *n\_bytes=0*, *buffer* может быть `NULL`.403404> **Примечание**405>406> Передача *n\_bytes=0* в эту функцию не является надёжным способом определения битовой длины значения.407408Чтобы получить всё значение Python неизвестного размера, функцию можно вызвать дважды: сначала для определения размера буфера, затем для его заполнения:409410```c411// Запрос необходимого объёма памяти.412Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);413if (expected < 0) {414    // Не удалось. Установлено исключение Python с указанием причины.415    return NULL;416}417assert(expected != 0);  // Невозможно согласно определению API.418uint8_t *bignum = malloc(expected);419if (!bignum) {420    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");421    return NULL;422}423// Безопасно получить всё значение.424Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);425if (bytes < 0) {  // Установлено исключение.426    free(bignum);427    return NULL;428}429else if (bytes > expected) {  // Этого не должно быть возможно.430    PyErr_SetString(PyExc_RuntimeError,431        "Unexpected bignum truncation after a size check.");432    free(bignum);433    return NULL;434}435// Ожидаемый успех с учётом предварительной проверки выше.436// ... использовать bignum ...437free(bignum);438```439440*flags* может быть либо `-1` (`Py_ASNATIVEBYTES_DEFAULTS`) для выбора значений по умолчанию, поведение которых наиболее похоже на приведение C, либо комбинацией других флагов из таблицы ниже. Обратите внимание, что `-1` нельзя комбинировать с другими флагами.441442В настоящее время `-1` соответствует `Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER`.443444| Флаг | Значение |445| --- | --- |446| Py\_ASNATIVEBYTES\_DEFAULTS *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* | `-1` |447| Py\_ASNATIVEBYTES\_BIG\_ENDIAN *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* | `0` |448| Py\_ASNATIVEBYTES\_LITTLE\_ENDIAN *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* | `1` |449| Py\_ASNATIVEBYTES\_NATIVE\_ENDIAN *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* | `3` |450| Py\_ASNATIVEBYTES\_UNSIGNED\_BUFFER *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* | `4` |451| Py\_ASNATIVEBYTES\_REJECT\_NEGATIVE *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* | `8` |452| Py\_ASNATIVEBYTES\_ALLOW\_INDEX *Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.* | `16` |453454Указание `Py_ASNATIVEBYTES_NATIVE_ENDIAN` переопределяет любые другие флаги порядка байтов. Передача `2` зарезервирована.455456По умолчанию будет запрошен буфер достаточного размера для включения знакового бита. Например, при преобразовании 128 с *n\_bytes=1* функция вернёт 2 (или больше), чтобы сохранить нулевой знаковый бит.457458Если указан `Py_ASNATIVEBYTES_UNSIGNED_BUFFER`, нулевой знаковый бит будет опущен при расчёте размера. Это позволяет, например, 128 поместиться в однобайтовый буфер. Если впоследствии целевой буфер будет трактоваться как знаковый, положительное входное значение может стать отрицательным. Обратите внимание, что флаг не влияет на обработку отрицательных значений: для них всегда запрашивается место под знаковый бит.459460Указание `Py_ASNATIVEBYTES_REJECT_NEGATIVE` приводит к установке исключения, если *pylong* отрицательно. Без этого флага отрицательные значения будут копироваться при условии, что достаточно места хотя бы для одного знакового бита, независимо от того, было ли указано `Py_ASNATIVEBYTES_UNSIGNED_BUFFER`.461462Если указан `Py_ASNATIVEBYTES_ALLOW_INDEX` и передано нецелое значение, сначала будет вызван его метод [`__index__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__index__). Это может привести к выполнению кода Python и возможности выполнения других потоков, что может вызвать изменения других объектов или используемых значений. Когда *flags* равно `-1`, эта опция не установлена, и нецелые значения вызовут [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError).463464> **Примечание**465>466> С флагами по умолчанию *flags* (`-1`, или *UNSIGNED\_BUFFER* без *REJECT\_NEGATIVE*) несколько целых чисел Python могут отображаться на одно значение без переполнения. Например, и `255`, и `-1` помещаются в однобайтовый буфер и устанавливают все его биты. Это соответствует типичному поведению приведения в C.467468Добавлено в версии 3.13.469470#### `PyLong_AsPid(pid)`471472Макрос для преобразования целого числа Python в идентификатор процесса.473474Он может быть определён как псевдоним для [`PyLong_AsLong()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsLong), [`PyLong_FromLongLong()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FromLongLong) или [`PyLong_AsInt()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsInt) в зависимости от размера типа PID в системе.475476Добавлено в версии 3.2.477478#### `int PyLong_GetSign(PyObject *obj, int *sign)`479480Получить знак целочисленного объекта *obj*.481482В случае успеха присвоить *\*sign* знак целого числа (0, -1 или +1 для нуля, отрицательного или положительного числа соответственно) и вернуть 0.483484В случае ошибки вернуть -1 с установленным исключением. Эта функция всегда завершается успешно, если *obj* является [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) или его подтипом.485486Добавлено в версии 3.14.487488#### `int PyLong_IsPositive(PyObject *obj)`489490Проверить, является ли целочисленный объект *obj* положительным (`obj > 0`).491492Если *obj* является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) или его подтипа, вернуть `1`, если он положительный, и `0` в противном случае. Иначе установить исключение и вернуть `-1`.493494Добавлено в версии 3.14.495496#### `int PyLong_IsNegative(PyObject *obj)`497498Проверить, является ли целочисленный объект *obj* отрицательным (`obj < 0`).499500Если *obj* является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) или его подтипа, вернуть `1`, если он отрицательный, и `0` в противном случае. Иначе установить исключение и вернуть `-1`.501502Добавлено в версии 3.14.503504#### `int PyLong_IsZero(PyObject *obj)`505506Проверить, является ли целочисленный объект *obj* нулём.507508Если *obj* является экземпляром [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject) или его подтипа, вернуть `1`, если он равен нулю, и `0` в противном случае. Иначе установить исключение и вернуть `-1`.509510Добавлено в версии 3.14.511512#### `PyObject *PyLong_GetInfo(void)`513514*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*515516В случае успеха возвращает доступный только для чтения [именованный кортеж](https://python-all.ru/3.16/glossary.html#term-named-tuple), содержащий информацию о внутреннем представлении целых чисел в Python. Описание отдельных полей см. в [`sys.int_info`](https://python-all.ru/3.16/library/sys.html#sys.int_info).517518При ошибке возвращает `NULL` с установленным исключением.519520Добавлено в версии 3.1.521522#### `int PyUnstable_Long_IsCompact(const PyLongObject *op)`523524> *Это [нестабильное API](https://python-all.ru/3.16/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*525526Возвращает 1, если *op* компактный, и 0 в противном случае.527528Эта функция позволяет критичному к производительности коду реализовать «быстрый путь» для малых целых чисел. Для компактных значений используйте [`PyUnstable_Long_CompactValue()`](https://python-all.ru/3.16/c-api/long.html#c.PyUnstable_Long_CompactValue); для остальных используйте [`PyLong_As*`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsSize_t) или [`PyLong_AsNativeBytes()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_AsNativeBytes).529530Ожидается, что ускорение будет незначительным для большинства пользователей.531532Какие именно значения считаются компактными, является деталью реализации и может измениться.533534Добавлено в версии 3.12.535536#### `Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)`537538> *Это [нестабильное API](https://python-all.ru/3.16/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*539540Если *op* компактный, как определено с помощью [`PyUnstable_Long_IsCompact()`](https://python-all.ru/3.16/c-api/long.html#c.PyUnstable_Long_IsCompact), вернуть его значение.541542В противном случае возвращаемое значение не определено.543544Добавлено в версии 3.12.545546## Экспорт API547548Добавлено в версии 3.14.549550#### `type PyLongLayout`551552*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) (включая все члены), начиная с версии 3.15.*553554Макет массива «цифр» («лимпов» в терминологии GMP), используемый для представления абсолютного значения целых чисел произвольной точности.555556Используйте [`PyLong_GetNativeLayout()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_GetNativeLayout), чтобы получить собственный макет объектов [`int`](https://python-all.ru/3.16/library/functions.html#int) Python, которые внутри используются для целых чисел с «достаточно большим» абсолютным значением.557558См. также [`sys.int_info`](https://python-all.ru/3.16/library/sys.html#sys.int_info), который предоставляет аналогичную информацию в Python.559560#### `uint8_t bits_per_digit`561562Количество битов на цифру. Например, 15-битная цифра означает, что биты 0-14 содержат значимую информацию.563564#### `uint8_t digit_size`565566Размер цифры в байтах. Например, для 15-битной цифры потребуется не менее 2 байт.567568#### `int8_t digits_order`569570Порядок цифр:571572- `1` – сначала старшая цифра573- `-1` – сначала младшая цифра574575#### `int8_t digit_endianness`576577Порядок байтов в цифре:578579- `1` – сначала старший байт (big endian)580- `-1` – сначала младший байт (little endian)581582#### `const PyLongLayout *PyLong_GetNativeLayout(void)`583584*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*585586Получает собственный макет объектов [`int`](https://python-all.ru/3.16/library/functions.html#int) Python.587588См. структуру [`PyLongLayout`](https://python-all.ru/3.16/c-api/long.html#c.PyLongLayout).589590Функцию нельзя вызывать до инициализации Python или после финализации Python. Возвращаемый макет действителен до завершения Python. Макет одинаков для всех под-интерпретаторов Python в процессе, поэтому его можно кэшировать.591592#### `type PyLongExport`593594*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) (включая все члены) начиная с версии 3.15.*595596Экспорт объекта [`int`](https://python-all.ru/3.16/library/functions.html#int) Python.597598Есть два случая:599600- Если [`digits`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.digits) равно `NULL`, используйте только поле [`value`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.value).601- Если [`digits`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.digits) не равно `NULL`, используйте поля [`negative`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.negative), [`ndigits`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.ndigits) и `digits`.602603#### `int64_t value`604605Собственное целочисленное значение экспортируемого объекта [`int`](https://python-all.ru/3.16/library/functions.html#int). Допустимо только если [`digits`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.digits) равно `NULL`.606607#### `uint8_t negative`608609`1` если число отрицательное, `0` в противном случае. Допустимо только если [`digits`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.digits) не равно `NULL`.610611#### `Py_ssize_t ndigits`612613Количество цифр в массиве [`digits`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport.digits). Допустимо только если `digits` не равно `NULL`.614615#### `const void *digits`616617Массив беззнаковых разрядов, доступный только для чтения. Может быть `NULL`.618619#### `int PyLong_Export(PyObject *obj, PyLongExport *export_long)`620621*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*622623Экспортирует объект Python [`int`](https://python-all.ru/3.16/library/functions.html#int).624625*export\_long* должен указывать на структуру [`PyLongExport`](https://python-all.ru/3.16/c-api/long.html#c.PyLongExport), выделенную вызывающим. Он не должен быть `NULL`.626627При успехе заполняет *\*export\_long* и возвращает `0`. При ошибке устанавливает исключение и возвращает `-1`.628629[`PyLong_FreeExport()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FreeExport) должен вызываться, когда экспорт больше не нужен.630631> **Деталь реализации CPython:** Эта функция всегда завершается успешно, если *obj* является объектом Python [`int`](https://python-all.ru/3.16/library/functions.html#int) или его подклассом.632633#### `void PyLong_FreeExport(PyLongExport *export_long)`634635*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*636637Освобождает экспорт *export\_long*, созданный [`PyLong_Export()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_Export).638639**Деталь реализации CPython:** Вызов [`PyLong_FreeExport()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FreeExport) необязателен, если *export\_long-\>digits* равен `NULL`.640641## PyLongWriter API642643API [`PyLongWriter`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter) можно использовать для импорта целого числа.644645Добавлено в версии 3.14.646647#### `type PyLongWriter`648649*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) (как непрозрачная структура) начиная с версии 3.15.*650651Экземпляр писателя Python [`int`](https://python-all.ru/3.16/library/functions.html#int).652653Экземпляр должен быть уничтожен с помощью [`PyLongWriter_Finish()`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter_Finish) или [`PyLongWriter_Discard()`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter_Discard).654655#### `PyLongWriter *PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)`656657*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*658659Создаёт [`PyLongWriter`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter).660661При успехе выделяет *\*digits* и возвращает писатель. При ошибке устанавливает исключение и возвращает `NULL`.662663*negative* равен `1`, если число отрицательное, или `0` в противном случае.664665*ndigits* – количество разрядов в массиве *digits*. Оно должно быть больше 0.666667*digits* не должен быть NULL.668669После успешного вызова этой функции вызывающий должен заполнить массив разрядов *digits*, а затем вызвать [`PyLongWriter_Finish()`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter_Finish), чтобы получить объект Python [`int`](https://python-all.ru/3.16/library/functions.html#int). Расположение *digits* описано в [`PyLong_GetNativeLayout()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_GetNativeLayout).670671Разряды должны находиться в диапазоне \[`0`; `(1 << bits_per_digit) - 1`\] (где [`bits_per_digit`](https://python-all.ru/3.16/c-api/long.html#c.PyLongLayout.bits_per_digit) – количество бит на разряд). Любые неиспользуемые старшие разряды должны быть установлены в `0`.672673В качестве альтернативы можно вызвать [`PyLongWriter_Discard()`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter_Discard) для уничтожения экземпляра писателя без создания объекта [`int`](https://python-all.ru/3.16/library/functions.html#int).674675#### `PyObject *PyLongWriter_Finish(PyLongWriter *writer)`676677*Возвращаемое значение: новая ссылка.*678679*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*680681Завершает [`PyLongWriter`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter), созданный [`PyLongWriter_Create()`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter_Create).682683При успехе возвращает объект Python [`int`](https://python-all.ru/3.16/library/functions.html#int). При ошибке устанавливает исключение и возвращает `NULL`.684685Функция заботится о нормализации разрядов и при необходимости преобразует объект в компактное целое число.686687Экземпляр писателя и массив *digits* становятся недействительными после вызова.688689#### `void PyLongWriter_Discard(PyLongWriter *writer)`690691*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*692693Отменяет объект [`PyLongWriter`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter), созданный с помощью [`PyLongWriter_Create()`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter_Create).694695Если *writer* равен `NULL`, операция не выполняется.696697Экземпляр писателя и массив *digits* становятся недействительными после вызова.698699## Устаревший API700701Эти макросы [мягко устарели](https://python-all.ru/3.16/glossary.html#term-soft-deprecated). Они описывают параметры внутреннего представления экземпляров [`PyLongObject`](https://python-all.ru/3.16/c-api/long.html#c.PyLongObject).702703Используйте [`PyLong_GetNativeLayout()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_GetNativeLayout) вместе с [`PyLong_Export()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_Export) для чтения целочисленных данных или [`PyLongWriter`](https://python-all.ru/3.16/c-api/long.html#c.PyLongWriter) для их записи. В настоящее время они используют одну и ту же разметку, но спроектированы так, чтобы продолжать корректно работать, даже если внутреннее представление целых чисел в CPython изменится.704705#### `PyLong_SHIFT`706707Это эквивалентно [`bits_per_digit`](https://python-all.ru/3.16/c-api/long.html#c.PyLongLayout.bits_per_digit) в выводе [`PyLong_GetNativeLayout()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_GetNativeLayout).708709#### `PyLong_BASE`710711В настоящее время это эквивалентно 1 \<\< [PyLong\_SHIFT](https://python-all.ru/3.16/c-api/long.html#c.PyLong_SHIFT).712713#### `PyLong_MASK`714715В настоящее время это эквивалентно (1 \<\< [PyLong\_SHIFT](https://python-all.ru/3.16/c-api/long.html#c.PyLong_SHIFT)) - 1716