Integer-Objekte

Alle ganzen Zahlen werden als „long“ Integer-Objekte beliebiger Größe implementiert.

Bei einem Fehler geben die meisten PyLong_As* APIs (return type)-1 zurück, was nicht von einer Zahl zu unterscheiden ist. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

type PyLongObject

Teil der Limited API (als opaker Struct).

Dieser Untertyp von PyObject repräsentiert ein Python-Integer-Objekt.

PyTypeObject PyLong_Type

Teil der Stable ABI.

Diese Instanz von PyTypeObject repräsentiert den Python-Integer-Typ. Dies ist dasselbe Objekt wie int auf der Python-Ebene.

int PyLong_Check(PyObject *p)

Gibt wahr zurück, wenn das Argument ein PyLongObject oder ein Untertyp von PyLongObject ist. Diese Funktion ist immer erfolgreich.

int PyLong_CheckExact(PyObject *p)

Gibt wahr zurück, wenn das Argument ein PyLongObject, aber kein Untertyp von PyLongObject ist. Diese Funktion ist immer erfolgreich.

PyObject *PyLong_FromLong(long v)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject-Objekt aus v zurück oder NULL bei einem Fehler.

CPython Implementierungsdetail: CPython unterhält ein Array von Integer-Objekten für alle ganzen Zahlen zwischen -5 und 256. Wenn Sie eine Ganzzahl in diesem Bereich erstellen, erhalten Sie tatsächlich nur eine Referenz auf das vorhandene Objekt.

PyObject *PyLong_FromUnsignedLong(unsigned long v)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject-Objekt aus einem C unsigned long zurück oder NULL bei einem Fehler.

PyObject *PyLong_FromSsize_t(Py_ssize_t v)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject-Objekt aus einem C Py_ssize_t zurück oder NULL bei einem Fehler.

PyObject *PyLong_FromSize_t(size_t v)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject-Objekt aus einem C size_t zurück oder NULL bei einem Fehler.

PyObject *PyLong_FromLongLong(long long v)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject-Objekt aus einem C long long zurück oder NULL bei einem Fehler.

PyObject *PyLong_FromInt32(int32_t value)

PyObject *PyLong_FromInt64(int64_t value)

Teil des Stable ABI seit Version 3.14.

Gibt ein neues PyLongObject-Objekt aus einem vorzeichenbehafteten C int32_t oder int64_t zurück oder NULL mit gesetzter Ausnahme bei einem Fehler.

Hinzugefügt in Version 3.14.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject-Objekt aus einem C unsigned long long zurück oder NULL bei einem Fehler.

PyObject *PyLong_FromUInt32(uint32_t value)

PyObject *PyLong_FromUInt64(uint64_t value)

Teil des Stable ABI seit Version 3.14.

Gibt ein neues PyLongObject-Objekt aus einem vorzeichenlosen C uint32_t oder uint64_t zurück oder NULL mit gesetzter Ausnahme bei einem Fehler.

Hinzugefügt in Version 3.14.

PyObject *PyLong_FromDouble(double v)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject-Objekt aus dem ganzzahligen Teil von v zurück oder NULL bei einem Fehler.

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

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues PyLongObject basierend auf dem Zeichenkettenwert in str zurück, der gemäß der Radix in base interpretiert wird, oder NULL bei einem Fehler. Wenn pend nicht NULL ist, wird *pend bei Erfolg auf das Ende von str oder bei einem Fehler auf das erste nicht verarbeitbare Zeichen zeigen. Wenn base 0 ist, wird str gemäß der Definition der Integer-Literale interpretiert; in diesem Fall löst eine führende Null in einer nicht-null Dezimalzahl einen ValueError aus. Wenn base nicht 0 ist, muss es zwischen 2 und 36 (einschließlich) liegen. Führende und nachfolgende Leerzeichen sowie einzelne Unterstriche nach einer Basisangabe und zwischen Ziffern werden ignoriert. Wenn keine Ziffern vorhanden sind oder str nach den Ziffern und nachfolgenden Leerzeichen nicht NULL-terminiert ist, wird ein ValueError ausgelöst.

Siehe auch

Die Funktionen PyLong_AsNativeBytes() und PyLong_FromNativeBytes() können verwendet werden, um ein PyLongObject in/aus einem Byte-Array in Basis 256 zu konvertieren.

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)

Rückgabewert: Neue Referenz.

Konvertiert eine Sequenz von Unicode-Ziffern in der Zeichenkette u in einen Python-Ganzzahlwert.

Hinzugefügt in Version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Erstellt eine Python-Ganzzahl aus dem Zeiger p. Der Zeigerwert kann mit PyLong_AsVoidPtr() aus dem resultierenden Wert abgerufen werden.

PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)

Teil des Stable ABI seit Version 3.14.

Erstellt eine Python-Ganzzahl aus dem Wert, der in den ersten n_bytes des buffer enthalten ist, interpretiert als zweierkomplementierte vorzeichenbehaftete Zahl.

flags sind wie für PyLong_AsNativeBytes(). Die Übergabe von -1 wählt die native Endianness aus, mit der CPython kompiliert wurde, und geht davon aus, dass das höchstwertige Bit ein Vorzeichenbit ist. Die Übergabe von Py_ASNATIVEBYTES_UNSIGNED_BUFFER ergibt dasselbe Ergebnis wie der Aufruf von PyLong_FromUnsignedNativeBytes(). Andere Flags werden ignoriert.

Hinzugefügt in Version 3.13.

PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)

Teil des Stable ABI seit Version 3.14.

Erstellt eine Python-Ganzzahl aus dem Wert, der in den ersten n_bytes des buffer enthalten ist, interpretiert als vorzeichenlose Zahl.

flags sind wie für PyLong_AsNativeBytes(). Die Übergabe von -1 wählt die native Endianness aus, mit der CPython kompiliert wurde, und geht davon aus, dass das höchstwertige Bit kein Vorzeichenbit ist. Andere Flags als die Endianness werden ignoriert.

Hinzugefügt in Version 3.13.

long PyLong_AsLong(PyObject *obj)

Teil der Stable ABI.

Gibt eine C-Darstellung long von obj zurück. Wenn obj keine Instanz von PyLongObject ist, wird zuerst seine __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

Löst einen OverflowError aus, wenn der Wert von obj außerhalb des Bereichs für ein long liegt.

Gibt -1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

Geändert in Version 3.8: Verwendet __index__(), falls verfügbar.

Geändert in Version 3.10: Diese Funktion verwendet nicht mehr __int__().

long PyLong_AS_LONG(PyObject *obj)

Ein soft deprecated Alias. Exakt äquivalent zu der bevorzugten Funktion PyLong_AsLong. Insbesondere kann sie mit OverflowError oder einer anderen Ausnahme fehlschlagen.

Veraltet seit Version 3.14: Die Funktion ist soft deprecated.

int PyLong_AsInt(PyObject *obj)

Teil des Stable ABI seit Version 3.13.

Ähnlich wie PyLong_AsLong(), speichert das Ergebnis jedoch in einem C int anstelle eines C long.

Hinzugefügt in Version 3.13.

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Teil der Stable ABI.

Gibt eine C-Darstellung long von obj zurück. Wenn obj keine Instanz von PyLongObject ist, wird zuerst seine __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

Wenn der Wert von obj größer als LONG_MAX oder kleiner als LONG_MIN ist, wird *overflow auf 1 bzw. -1 gesetzt und -1 zurückgegeben; andernfalls wird *overflow auf 0 gesetzt. Wenn eine andere Ausnahme auftritt, wird *overflow auf 0 gesetzt und wie üblich -1 zurückgegeben.

Gibt -1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

Geändert in Version 3.8: Verwendet __index__(), falls verfügbar.

Geändert in Version 3.10: Diese Funktion verwendet nicht mehr __int__().

long long PyLong_AsLongLong(PyObject *obj)

Teil der Stable ABI.

Gibt eine C-Darstellung long long von obj zurück. Wenn obj keine Instanz von PyLongObject ist, wird zuerst seine __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

Löst einen OverflowError aus, wenn der Wert von obj außerhalb des Bereichs für ein long long liegt.

Gibt -1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

Geändert in Version 3.8: Verwendet __index__(), falls verfügbar.

Geändert in Version 3.10: Diese Funktion verwendet nicht mehr __int__().

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

Teil der Stable ABI.

Gibt eine C-Darstellung long long von obj zurück. Wenn obj keine Instanz von PyLongObject ist, wird zuerst seine __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

Wenn der Wert von obj größer als LLONG_MAX oder kleiner als LLONG_MIN ist, wird *overflow auf 1 bzw. -1 gesetzt und -1 zurückgegeben; andernfalls wird *overflow auf 0 gesetzt. Wenn eine andere Ausnahme auftritt, wird *overflow auf 0 gesetzt und wie üblich -1 zurückgegeben.

Gibt -1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

Hinzugefügt in Version 3.2.

Geändert in Version 3.8: Verwendet __index__(), falls verfügbar.

Geändert in Version 3.10: Diese Funktion verwendet nicht mehr __int__().

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

Teil der Stable ABI.

Gibt eine C-Darstellung Py_ssize_t von pylong zurück. pylong muss eine Instanz von PyLongObject sein.

Löst einen OverflowError aus, wenn der Wert von pylong außerhalb des Bereichs für ein Py_ssize_t liegt.

Gibt -1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Teil der Stable ABI.

Gibt eine C-Darstellung unsigned long von pylong zurück. pylong muss eine Instanz von PyLongObject sein.

Löst einen OverflowError aus, wenn der Wert von pylong außerhalb des Bereichs für ein unsigned long liegt.

Gibt (unsigned long)-1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

size_t PyLong_AsSize_t(PyObject *pylong)

Teil der Stable ABI.

Gibt eine C-Darstellung size_t von pylong zurück. pylong muss eine Instanz von PyLongObject sein.

Löst einen OverflowError aus, wenn der Wert von pylong außerhalb des Bereichs für ein size_t liegt.

Gibt (size_t)-1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Teil der Stable ABI.

Gibt eine C-Darstellung unsigned long long von pylong zurück. pylong muss eine Instanz von PyLongObject sein.

Löst OverflowError aus, wenn der Wert von pylong außerhalb des gültigen Bereichs für einen unsigned long long liegt.

Gibt bei einem Fehler (unsigned long long)-1 zurück. Verwenden Sie PyErr_Occurred(), um dies zu unterscheiden.

Geändert in Version 3.1: Ein negativer pylong löst nun OverflowError aus, nicht TypeError.

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)

Teil der Stable ABI.

Gibt eine C unsigned long-Repräsentation von obj zurück. Wenn obj keine Instanz von PyLongObject ist, wird zuerst deren __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

Wenn der Wert von obj außerhalb des gültigen Bereichs für einen unsigned long liegt, wird die Reduktion dieses Werts modulo ULONG_MAX + 1 zurückgegeben.

Gibt (unsigned long)-1 bei einem Fehler zurück. Verwenden Sie PyErr_Occurred(), um dies zu disambiguieren.

Geändert in Version 3.8: Verwendet __index__(), falls verfügbar.

Geändert in Version 3.10: Diese Funktion verwendet nicht mehr __int__().

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)

Teil der Stable ABI.

Gibt eine C unsigned long long-Repräsentation von obj zurück. Wenn obj keine Instanz von PyLongObject ist, wird zuerst deren __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

Wenn der Wert von obj außerhalb des gültigen Bereichs für einen unsigned long long liegt, wird die Reduktion dieses Werts modulo ULLONG_MAX + 1 zurückgegeben.

Gibt bei einem Fehler (unsigned long long)-1 zurück. Verwenden Sie PyErr_Occurred(), um dies zu unterscheiden.

Geändert in Version 3.8: Verwendet __index__(), falls verfügbar.

Geändert in Version 3.10: Diese Funktion verwendet nicht mehr __int__().

int PyLong_AsInt32(PyObject *obj, int32_t *value)

int PyLong_AsInt64(PyObject *obj, int64_t *value)

Teil des Stable ABI seit Version 3.14.

Setzt *value auf eine vorzeichenbehaftete C int32_t- oder int64_t-Repräsentation von obj.

Wenn obj keine Instanz von PyLongObject ist, wird zuerst deren __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

Wenn der Wert von obj außerhalb des gültigen Bereichs liegt, wird ein OverflowError ausgelöst.

Setzt *value und gibt bei Erfolg 0 zurück. Setzt eine Ausnahme und gibt bei einem Fehler -1 zurück.

value darf nicht NULL sein.

Hinzugefügt in Version 3.14.

int PyLong_AsUInt32(PyObject *obj, uint32_t *value)

int PyLong_AsUInt64(PyObject *obj, uint64_t *value)

Teil des Stable ABI seit Version 3.14.

Setzt *value auf eine vorzeichenlose C uint32_t- oder uint64_t-Repräsentation von obj.

Wenn obj keine Instanz von PyLongObject ist, wird zuerst deren __index__()-Methode (falls vorhanden) aufgerufen, um sie in ein PyLongObject zu konvertieren.

• Wenn obj negativ ist, wird ein ValueError ausgelöst.

• Wenn der Wert von obj außerhalb des gültigen Bereichs liegt, wird ein OverflowError ausgelöst.

Setzt *value und gibt bei Erfolg 0 zurück. Setzt eine Ausnahme und gibt bei einem Fehler -1 zurück.

value darf nicht NULL sein.

Hinzugefügt in Version 3.14.

double PyLong_AsDouble(PyObject *pylong)

Teil der Stable ABI.

Gibt eine C double-Repräsentation von pylong zurück. pylong muss eine Instanz von PyLongObject sein.

Löst OverflowError aus, wenn der Wert von pylong außerhalb des gültigen Bereichs für einen double liegt.

Gibt bei einem Fehler -1.0 zurück. Verwenden Sie PyErr_Occurred(), um dies zu unterscheiden.

void *PyLong_AsVoidPtr(PyObject *pylong)

Teil der Stable ABI.

Konvertiert eine Python-Ganzzahl pylong in einen C void-Zeiger. Wenn pylong nicht konvertiert werden kann, wird ein OverflowError ausgelöst. Nur für Werte, die mit PyLong_FromVoidPtr() erstellt wurden, ist die Erzeugung eines nutzbaren void-Zeigers garantiert.

Gibt bei einem Fehler NULL zurück. Verwenden Sie PyErr_Occurred(), um dies zu unterscheiden.

Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)

Teil des Stable ABI seit Version 3.14.

Kopiert den Python-Ganzzahlwert pylong in einen nativen buffer der Größe n_bytes. Die flags können auf -1 gesetzt werden, um sich ähnlich wie bei einer C-Konvertierung zu verhalten, oder auf die unten dokumentierten Werte, um das Verhalten zu steuern.

Gibt -1 mit einer ausgelösten Ausnahme bei einem Fehler zurück. Dies kann passieren, wenn pylong nicht als Ganzzahl interpretiert werden kann oder wenn pylong negativ war und das Flag Py_ASNATIVEBYTES_REJECT_NEGATIVE gesetzt war.

Andernfalls wird die Anzahl der Bytes zurückgegeben, die zur Speicherung des Wertes benötigt werden. Wenn diese gleich n_bytes oder kleiner ist, wurde der gesamte Wert kopiert. Alle n_bytes des Puffers werden geschrieben: Große Puffer werden mit Nullen aufgefüllt.

Wenn der zurückgegebene Wert größer als n_bytes ist, wurde der Wert abgeschnitten: So viele der niedrigsten Bits des Wertes, wie hineinpassen, werden geschrieben, und die höheren Bits werden ignoriert. Dies entspricht dem typischen Verhalten eines C-Style-Downcasts.

Hinweis

Überlauf wird nicht als Fehler betrachtet. Wenn der zurückgegebene Wert größer als n_bytes ist, wurden die höchstwertigen Bits verworfen.

0 wird niemals zurückgegeben.

Werte werden immer als Zweierkomplement kopiert.

Anwendungsbeispiel

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.
}

Wenn n_bytes null ist, gibt die Funktion die Größe eines Puffers zurück, der groß genug wäre, um den Wert zu speichern. Dies kann größer sein als technisch notwendig, aber nicht unangemessen. Wenn n_bytes=0, kann buffer NULL sein.

Hinweis

Die Übergabe von n_bytes=0 an diese Funktion ist keine genaue Methode zur Bestimmung der Bitlänge des Wertes.

Um auf den gesamten Python-Wert unbekannter Größe zuzugreifen, kann die Funktion zweimal aufgerufen werden: zuerst, um die Puffergröße zu bestimmen, dann, um ihn zu füllen.

// 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 ist entweder -1 (Py_ASNATIVEBYTES_DEFAULTS), um Standardeinstellungen auszuwählen, die sich am ehesten wie eine C-Konvertierung verhalten, oder eine Kombination aus den anderen Flags in der unten stehenden Tabelle. Beachten Sie, dass -1 nicht mit anderen Flags kombiniert werden kann.

Derzeit entspricht -1 Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER.

Flag	Wert
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_ALLOW_INDEX	16

Die Angabe von Py_ASNATIVEBYTES_NATIVE_ENDIAN überschreibt alle anderen Endian-Flags. Die Übergabe von 2 ist reserviert.

Standardmäßig wird ein ausreichender Puffer angefordert, um ein Vorzeichenbit einzuschließen. Beispielsweise wird bei der Konvertierung von 128 mit n_bytes=1 die Funktion 2 (oder mehr) zurückgeben, um ein Vorzeichenbit von Null zu speichern.

Wenn Py_ASNATIVEBYTES_UNSIGNED_BUFFER angegeben ist, wird ein Vorzeichenbit von Null von den Größenberechnungen ausgeschlossen. Dies ermöglicht es beispielsweise, dass 128 in einen ein Byte großen Puffer passen. Wenn der Zielpuffer später als vorzeichenbehaftet behandelt wird, kann ein positiver Eingabewert negativ werden. Beachten Sie, dass das Flag die Behandlung von negativen Werten nicht beeinflusst: Für diese wird immer Platz für ein Vorzeichenbit angefordert.

Die Angabe von Py_ASNATIVEBYTES_REJECT_NEGATIVE führt zum Setzen einer Ausnahme, wenn pylong negativ ist. Ohne dieses Flag werden negative Werte kopiert, vorausgesetzt, es ist genügend Platz für mindestens ein Vorzeichenbit vorhanden, unabhängig davon, ob Py_ASNATIVEBYTES_UNSIGNED_BUFFER angegeben wurde.

Wenn Py_ASNATIVEBYTES_ALLOW_INDEX angegeben ist und ein Wert übergeben wird, der keine Ganzzahl ist, wird zuerst dessen __index__()-Methode aufgerufen. Dies kann dazu führen, dass Python-Code ausgeführt wird und andere Threads ausgeführt werden dürfen, was zu Änderungen an anderen verwendeten Objekten oder Werten führen könnte. Wenn flags -1 ist, ist diese Option nicht gesetzt und Nicht-Ganzzahlwerte lösen TypeError aus.

Hinweis

Mit den Standard-flags (-1 oder UNSIGNED_BUFFER ohne REJECT_NEGATIVE) können mehrere Python-Integer ohne Überlauf auf einen einzigen Wert abgebildet werden. Beispielsweise passen sowohl 255 als auch -1 in einen ein Byte großen Puffer und setzen alle seine Bits. Dies entspricht dem typischen Verhalten von C-Konvertierungen.

Hinzugefügt in Version 3.13.

int PyLong_GetSign(PyObject *obj, int *sign)

Holt das Vorzeichen des Integer-Objekts obj.

Bei Erfolg wird *sign auf das Integer-Vorzeichen (0, -1 oder +1 für Null, negative oder positive Integer) gesetzt und 0 zurückgegeben.

Bei einem Fehler wird -1 zurückgegeben, wobei eine Ausnahme gesetzt wird. Diese Funktion ist immer erfolgreich, wenn obj ein PyLongObject oder eine Unterklasse davon ist.

Hinzugefügt in Version 3.14.

int PyLong_IsPositive(PyObject *obj)

Prüft, ob das Integer-Objekt obj positiv ist (obj > 0).

Wenn obj eine Instanz von PyLongObject oder einer Unterklasse davon ist, wird 1 zurückgegeben, wenn es positiv ist, und 0 andernfalls. Andernfalls wird eine Ausnahme gesetzt und -1 zurückgegeben.

Hinzugefügt in Version 3.14.

int PyLong_IsNegative(PyObject *obj)

Prüft, ob das Integer-Objekt obj negativ ist (obj < 0).

Wenn obj eine Instanz von PyLongObject oder einer Unterklasse davon ist, wird 1 zurückgegeben, wenn es negativ ist, und 0 andernfalls. Andernfalls wird eine Ausnahme gesetzt und -1 zurückgegeben.

Hinzugefügt in Version 3.14.

int PyLong_IsZero(PyObject *obj)

Prüft, ob das Integer-Objekt obj Null ist.

Wenn obj eine Instanz von PyLongObject oder einer Unterklasse davon ist, wird 1 zurückgegeben, wenn es Null ist, und 0 andernfalls. Andernfalls wird eine Ausnahme gesetzt und -1 zurückgegeben.

Hinzugefügt in Version 3.14.

PyObject *PyLong_GetInfo(void)

Teil der Stable ABI.

Bei Erfolg wird ein schreibgeschütztes benanntes Tupel zurückgegeben, das Informationen über die interne Darstellung von Ganzzahlen in Python enthält. Die Beschreibung der einzelnen Felder finden Sie unter sys.int_info.

Bei einem Fehler wird NULL mit einer gesetzten Ausnahme zurückgegeben.

Hinzugefügt in Version 3.1.

int PyUnstable_Long_IsCompact(const PyLongObject *op)

Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Gibt 1 zurück, wenn op kompakt ist, andernfalls 0.

Diese Funktion ermöglicht es leistungskritischem Code, einen „Schnellweg“ für kleine Ganzzahlen zu implementieren. Für kompakte Werte verwenden Sie PyUnstable_Long_CompactValue(); für andere fallen Sie auf eine PyLong_As*-Funktion oder PyLong_AsNativeBytes() zurück.

Die Geschwindigkeitssteigerung wird für die meisten Benutzer voraussichtlich vernachlässigbar sein.

Was genau als kompakt gilt, ist Implementierungsdetail und kann sich ändern.

Hinzugefügt in Version 3.12.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

Dies ist eine Instabile API. Sie kann sich ohne Vorwarnung in kleineren Releases ändern.

Wenn op kompakt ist, wie von PyUnstable_Long_IsCompact() bestimmt, wird sein Wert zurückgegeben.

Andernfalls ist der Rückgabewert undefiniert.

Hinzugefügt in Version 3.12.

Export API

Hinzugefügt in Version 3.14.

struct PyLongLayout

Layout eines Arrays von „Ziffern“ („limbs“ in der GMP-Terminologie), das zur Darstellung des Absolutbetrags für Ganzzahlen beliebiger Präzision verwendet wird.

Verwenden Sie PyLong_GetNativeLayout(), um das native Layout von Python int-Objekten zu erhalten, das intern für Ganzzahlen mit „groß genug“ absolutem Wert verwendet wird.

Siehe auch sys.int_info, das ähnliche Informationen in Python bereitstellt.

uint8_t bits_per_digit

Bits pro Ziffer. Beispielsweise bedeutet eine 15-Bit-Ziffer, dass Bits 0-14 aussagekräftige Informationen enthalten.

uint8_t digit_size

Größe einer Ziffer in Bytes. Beispielsweise benötigt eine 15-Bit-Ziffer mindestens 2 Bytes.

int8_t digits_order

Reihenfolge der Ziffern

• 1 für höchstwertige Ziffer zuerst

• -1 für niederwertigste Ziffer zuerst

int8_t digit_endianness

Endianness der Ziffer

• 1 für höchstwertiges Byte zuerst (Big-Endian)

• -1 für niederwertigstes Byte zuerst (Little-Endian)

const PyLongLayout *PyLong_GetNativeLayout(void)

Ruft das native Layout von Python int-Objekten ab.

Siehe die Struktur PyLongLayout.

Die Funktion darf nicht vor der Initialisierung von Python oder nach der Finalisierung von Python aufgerufen werden. Das zurückgegebene Layout ist bis zur Finalisierung von Python gültig. Das Layout ist für alle Python-Subinterpreter in einem Prozess dasselbe und kann daher gecacht werden.

struct PyLongExport

Export eines Python int-Objekts.

Es gibt zwei Fälle:

• Wenn digits NULL ist, wird nur das Mitglied value verwendet.

• Wenn digits nicht NULL ist, verwenden Sie die Member negative, ndigits und digits.

int64_t value

Der native Ganzzahlwert des exportierten int-Objekts. Nur gültig, wenn digits NULL ist.

uint8_t negative

1, wenn die Zahl negativ ist, 0 andernfalls. Nur gültig, wenn digits nicht NULL ist.

Py_ssize_t ndigits

Anzahl der Ziffern im digits-Array. Nur gültig, wenn digits nicht NULL ist.

const void *digits

Schreibgeschütztes Array von vorzeichenlosen Ziffern. Kann NULL sein.

int PyLong_Export(PyObject *obj, PyLongExport *export_long)

Exportiert ein Python int-Objekt.

export_long muss auf eine vom Aufrufer zugewiesene PyLongExport-Struktur zeigen. Es darf nicht NULL sein.

Bei Erfolg wird *export_long gefüllt und 0 zurückgegeben. Im Fehlerfall wird eine Ausnahme gesetzt und -1 zurückgegeben.

PyLong_FreeExport() muss aufgerufen werden, wenn der Export nicht mehr benötigt wird.

CPython-Implementierungsdetail: Diese Funktion ist immer erfolgreich, wenn obj ein Python int-Objekt oder eine Unterklasse davon ist.

void PyLong_FreeExport(PyLongExport *export_long)

Gibt den von PyLong_Export() erstellten Export export_long frei.

CPython-Implementierungsdetail: Der Aufruf von PyLong_FreeExport() ist optional, wenn export_long->digits NULL ist.

PyLongWriter API

Die PyLongWriter API kann verwendet werden, um eine Ganzzahl zu importieren.

Hinzugefügt in Version 3.14.

struct PyLongWriter

Eine Python int Writer-Instanz.

Die Instanz muss von PyLongWriter_Finish() oder PyLongWriter_Discard() zerstört werden.

PyLongWriter *PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)

Erstellt einen PyLongWriter.

Bei Erfolg wird *digits zugewiesen und ein Writer zurückgegeben. Im Fehlerfall wird eine Ausnahme gesetzt und NULL zurückgegeben.

negative ist 1, wenn die Zahl negativ ist, und 0 andernfalls.

ndigits ist die Anzahl der Ziffern im digits-Array. Es muss größer als 0 sein.

digits darf nicht NULL sein.

Nach einem erfolgreichen Aufruf dieser Funktion sollte der Aufrufer das Array von Ziffern digits füllen und dann PyLongWriter_Finish() aufrufen, um eine Python int zu erhalten. Das Layout von digits wird durch PyLong_GetNativeLayout() beschrieben.

Ziffern müssen im Bereich [0; (1 << bits_per_digit) - 1] liegen (wobei bits_per_digit die Anzahl der Bits pro Ziffer ist). Alle nicht verwendeten höchstwertigen Ziffern müssen auf 0 gesetzt werden.

Alternativ kann PyLongWriter_Discard() aufgerufen werden, um die Writer-Instanz zu zerstören, ohne ein int-Objekt zu erstellen.

PyObject *PyLongWriter_Finish(PyLongWriter *writer)

Rückgabewert: Neue Referenz.

Beendet einen von PyLongWriter_Create() erstellten PyLongWriter.

Bei Erfolg wird ein Python int-Objekt zurückgegeben. Im Fehlerfall wird eine Ausnahme gesetzt und NULL zurückgegeben.

Die Funktion kümmert sich um die Normalisierung der Ziffern und konvertiert das Objekt bei Bedarf in eine kompakte Ganzzahl.

Die Writer-Instanz und das digits-Array sind nach dem Aufruf ungültig.

void PyLongWriter_Discard(PyLongWriter *writer)

Verwirft einen von PyLongWriter_Create() erstellten PyLongWriter.

Wenn writer NULL ist, wird keine Operation durchgeführt.

Die Writer-Instanz und das digits-Array sind nach dem Aufruf ungültig.