Целочисленные объекты¶
Все целые числа реализуются как «длинные» целочисленные объекты произвольного размера.
При ошибке большинство 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)¶
Возвращает true, если его аргумент является
PyLongObject
или подтипомPyLongObject
. Эта функция всегда успешна.
-
int PyLong_CheckExact(PyObject *p)¶
Возвращает true, если его аргумент является
PyLongObject
, но не является подтипомPyLongObject
. Эта функция всегда успешна.
-
PyObject *PyLong_FromLong(long v)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает новый объект
PyLongObject
из v, илиNULL
в случае неудачи.Текущая реализация хранит массив целочисленных объектов для всех целых чисел между
-5
и256
. Когда вы создаете int в этом диапазоне, вы фактически просто получаете обратно ссылку на существующий объект.
-
PyObject *PyLong_FromUnsignedLong(unsigned long v)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает новый объект
PyLongObject
из C unsigned long, илиNULL
в случае неудачи.
-
PyObject *PyLong_FromSsize_t(Py_ssize_t v)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает новый объект
PyLongObject
из CPy_ssize_t
, илиNULL
в случае неудачи.
-
PyObject *PyLong_FromSize_t(size_t v)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает новый объект
PyLongObject
из Csize_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 не является NULL-терминированным, будет выдано сообщениеValueError
.См.также
Методы Python
int.to_bytes()
иint.from_bytes()
для преобразованияPyLongObject
в/из массива байтов в базе256
. Вы можете вызвать их из языка Си, используяPyObject_CallMethod()
.
-
PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)¶
- Возвращаемое значение: Новая ссылка.
Преобразование последовательности цифр Unicode в строке u в целочисленное значение Python.
Added in version 3.3.
-
PyObject *PyLong_FromVoidPtr(void *p)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте целое число Python из указателя p. Значение указателя можно извлечь из полученного значения с помощью
PyLong_AsVoidPtr()
.
-
PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)¶
Создайте целое число Python из значения, содержащегося в первых n_байтах буфера buffer, интерпретируемое как двухкомпонентное знаковое число.
Флаги - как для
PyLong_AsNativeBytes()
. Если передать-1
, то будет выбран собственный эндианальный формат, с которым был скомпилирован CPython, и предполагается, что старший бит является битом знака. ПередачаPy_ASNATIVEBYTES_UNSIGNED_BUFFER
приведет к тому же результату, что и вызовPyLong_FromUnsignedNativeBytes()
. Другие флаги игнорируются.Added in version 3.13.
-
PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)¶
Создает целое число Python из значения, содержащегося в первых n_байтах буфера buffer, интерпретируемого как число без знака.
Флаги - как для
PyLong_AsNativeBytes()
. При передаче-1
будет выбран собственный endian, с которым был скомпилирован CPython, и предполагается, что старший бит не является битом знака. Флаги, отличные от endian, игнорируются.Added in version 3.13.
-
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__()
.
-
int PyLong_AsInt(PyObject *obj)¶
- Часть Стабильный ABI с версии 3.13.
Аналогично
PyLong_AsLong()
, но храните результат в C int, а не в C long.Added in version 3.13.
-
long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)¶
- Часть Стабильный ABI.
Возвращает представление C long для obj. Если 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)¶
- Часть Стабильный ABI.
Возвращает представление C long long для obj. Если 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)¶
- Часть Стабильный ABI.
Возвращает представление C long long для obj. Если obj не является экземпляром
PyLongObject
, сначала вызовите его метод__index__()
(если он есть), чтобы преобразовать его вPyLongObject
.Если значение obj больше
LLONG_MAX
или меньшеLLONG_MIN
, установите *overflow в1
или-1
, соответственно, и верните-1
; в противном случае установите *overflow в0
. Если произойдет любое другое исключение, установите *overflow в0
и верните-1
, как обычно.Возвращает
-1
при ошибке. ИспользуйтеPyErr_Occurred()
, чтобы определить ошибку.Added in version 3.2.
Изменено в версии 3.8: Используйте
__index__()
, если он доступен.Изменено в версии 3.10: Эта функция больше не будет использовать
__int__()
.
-
Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)¶
- Часть Стабильный ABI.
Возвращает C
Py_ssize_t
представление pylong. pylong должен быть экземпляромPyLongObject
.Поднимите
OverflowError
, если значение pylong выходит за пределы диапазона дляPy_ssize_t
.Возвращает
-1
при ошибке. ИспользуйтеPyErr_Occurred()
, чтобы определить ошибку.
-
unsigned long PyLong_AsUnsignedLong(PyObject *pylong)¶
- Часть Стабильный ABI.
Возвращает C unsigned long представление pylong. pylong должен быть экземпляром
PyLongObject
.Поднимите
OverflowError
, если значение pylong выходит за пределы диапазона для unsigned long.Возвращает
(unsigned long)-1
при ошибке. ИспользуйтеPyErr_Occurred()
, чтобы определить ошибку.
-
size_t PyLong_AsSize_t(PyObject *pylong)¶
- Часть Стабильный ABI.
Возвращает C
size_t
представление pylong. pylong должен быть экземпляромPyLongObject
.Поднимите
OverflowError
, если значение pylong выходит за пределы диапазона дляsize_t
.Возвращает
(size_t)-1
при ошибке. ИспользуйтеPyErr_Occurred()
, чтобы определить ошибку.
-
unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)¶
- Часть Стабильный ABI.
Возвращает C unsigned long long представление pylong. pylong должен быть экземпляром
PyLongObject
.Поднимите
OverflowError
, если значение pylong выходит за пределы диапазона для unsigned long long.Возвращает
(unsigned long long)-1
при ошибке. ИспользуйтеPyErr_Occurred()
, чтобы определить ошибку.Изменено в версии 3.1: Отрицательный pylong теперь поднимает
OverflowError
, а неTypeError
.
-
unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)¶
- Часть Стабильный ABI.
Возвращает представление C unsigned long для obj. Если 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)¶
- Часть Стабильный ABI.
Возвращает представление C unsigned long long для obj. Если 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)¶
- Часть Стабильный ABI.
Возвращает C double представление pylong. pylong должен быть экземпляром
PyLongObject
.Поднимите
OverflowError
, если значение pylong выходит за пределы диапазона для double.Возвращает
-1.0
при ошибке. ИспользуйтеPyErr_Occurred()
, чтобы определить ошибку.
-
void *PyLong_AsVoidPtr(PyObject *pylong)¶
- Часть Стабильный ABI.
Преобразование целого числа Python pylong в указатель C void. Если pylong не может быть преобразовано, будет выдана ошибка
OverflowError
. Это гарантировано только для получения пригодного для использования указателя void для значений, созданных с помощьюPyLong_FromVoidPtr()
.Возвращает
NULL
при ошибке. ИспользуйтеPyErr_Occurred()
, чтобы определить ошибку.
-
Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)¶
Копирует целочисленное значение Python pylong в нативный буфер размером n_байт. Флаги flags могут быть установлены в
-1
, чтобы вести себя аналогично приведению на C, или в значения, описанные ниже, чтобы управлять поведением.Возвращает
-1
с исключением, вызванным при ошибке. Это может произойти, если pylong не может быть интерпретировано как целое число, или если pylong было отрицательным и был установлен флагPy_ASNATIVEBYTES_REJECT_NEGATIVE
.В противном случае возвращается количество байт, необходимых для хранения значения. Если оно равно или меньше n_байт, то было скопировано все значение. Записываются все n_байты буфера: большие буферы заполняются нулями.
Если возвращаемое значение больше, чем n_байт, то оно было усечено: записывается столько младших битов значения, сколько может поместиться, а старшие биты игнорируются. Это соответствует типичному поведению даунлоадера в стиле C.
Примечание
Переполнение не считается ошибкой. Если возвращаемое значение больше n_байт, то старшие биты отбрасываются.
0
никогда не будет возвращен.Значения всегда копируются в виде двух дополнений.
Пример использования:
int32_t value; Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1); if (bytes < 0) { // Failed. A Python exception was set with the reason. return NULL; } else if (bytes <= (Py_ssize_t)sizeof(value)) { // Success! } else { // Overflow occurred, but 'value' contains the truncated // lowest bits of pylong. }
Передача нуля в n_bytes вернет размер буфера, который будет достаточно большим, чтобы вместить значение. Это может быть больше, чем технически необходимо, но не необоснованно.
Примечание
Передача n_bytes=0 в эту функцию не является точным способом определения битовой длины значения.
Если n_bytes=0, buffer может быть
NULL
.Чтобы получить все значение Python неизвестного размера, функцию можно вызвать дважды: сначала для определения размера буфера, а затем для его заполнения:
// Ask how much space we need. Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1); if (expected < 0) { // Failed. A Python exception was set with the reason. return NULL; } assert(expected != 0); // Impossible per the API definition. uint8_t *bignum = malloc(expected); if (!bignum) { PyErr_SetString(PyExc_MemoryError, "bignum malloc failed."); return NULL; } // Safely get the entire value. Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1); if (bytes < 0) { // Exception has been set. free(bignum); return NULL; } else if (bytes > expected) { // This should not be possible. PyErr_SetString(PyExc_RuntimeError, "Unexpected bignum truncation after a size check."); free(bignum); return NULL; } // The expected success given the above pre-check. // ... use bignum ... free(bignum);
flags - это либо
-1
(Py_ASNATIVEBYTES_DEFAULTS
), чтобы выбрать значения по умолчанию, которые ведут себя наиболее похоже на приведение в C, либо комбинация других флагов, приведенных в таблице ниже. Обратите внимание, что-1
нельзя комбинировать с другими флагами.В настоящее время
-1
соответствуетPy_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER
.Флаг
Значение
-
Py_ASNATIVEBYTES_DEFAULTS¶
-1
-
Py_ASNATIVEBYTES_BIG_ENDIAN¶
0
-
Py_ASNATIVEBYTES_LITTLE_ENDIAN¶
1
-
Py_ASNATIVEBYTES_NATIVE_ENDIAN¶
3
-
Py_ASNATIVEBYTES_UNSIGNED_BUFFER¶
4
-
Py_ASNATIVEBYTES_REJECT_NEGATIVE¶
8
Указание
Py_ASNATIVEBYTES_NATIVE_ENDIAN
отменяет любые другие флаги endian. Передача2
зарезервирована.По умолчанию будет запрошен буфер, достаточный для хранения знакового бита. Например, при преобразовании 128 с n_bytes=1 функция вернет 2 (или больше), чтобы сохранить бит нулевого знака.
Если указан
Py_ASNATIVEBYTES_UNSIGNED_BUFFER
, то бит нулевого знака будет опущен при вычислении размера. Это позволяет, например, 128 поместить в однобайтовый буфер. Если буфер назначения впоследствии будет обработан как знаковый, то положительное входное значение может стать отрицательным. Обратите внимание, что этот флаг не влияет на обработку отрицательных значений: для них всегда запрашивается место для знакового бита.Указание
Py_ASNATIVEBYTES_REJECT_NEGATIVE
приводит к установке исключения, если pylong отрицательно. Без этого флага отрицательные значения будут скопированы при условии, что достаточно места хотя бы для одного знакового бита, независимо от того, был ли указанPy_ASNATIVEBYTES_UNSIGNED_BUFFER
.Примечание
При использовании флагов по умолчанию (
-1
, или UNSIGNED_BUFFER без REJECT_NEGATIVE) несколько целых чисел Python могут быть сопоставлены одному значению без переполнения. Например, и255
, и-1
помещаются в однобайтовый буфер и устанавливают все его биты. Это соответствует типичному поведению приведения в языке C.Added in version 3.13.
-
Py_ASNATIVEBYTES_DEFAULTS¶
-
int PyUnstable_Long_IsCompact(const PyLongObject *op)¶
- Это Нестабильный API. Она может меняться без предупреждения в небольших выпусках.
Возвращает 1, если op является компактным, 0 - в противном случае.
Эта функция позволяет критичному к производительности коду реализовать «быстрый путь» для небольших целых чисел. Для компактных значений используйте
PyUnstable_Long_CompactValue()
; для других возвращайтесь к функцииPyLong_As*
илиPyLong_AsNativeBytes()
.Ожидается, что для большинства пользователей ускорение будет незначительным.
То, какие именно значения считаются компактными, является деталью реализации и может быть изменено.
-
Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)¶
- Это Нестабильный API. Она может меняться без предупреждения в небольших выпусках.
Если op является компактным, что определяется
PyUnstable_Long_IsCompact()
, верните его значение.В противном случае возвращаемое значение не определено.