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

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

При ошибке большинство 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 из 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 не является 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.

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(), верните его значение.

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

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

Предыдущий раздел

Следующий раздел