String-Konvertierung und Formatierung

Funktionen zur Zahlenkonvertierung und formatierten Zeichenkettenausgabe.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

Teil der Stable ABI.

Gibt nicht mehr als size Bytes an str gemäß der Formatzeichenkette format und den zusätzlichen Argumenten aus. Siehe die Unix-manpage snprintf(3).

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

Teil der Stable ABI.

Gibt nicht mehr als size Bytes an str gemäß der Formatzeichenkette format und der variablen Argumentenliste va aus. Unix-manpage vsnprintf(3).

PyOS_snprintf() und PyOS_vsnprintf() sind Wrapper für die Standard-C-Bibliotheksfunktionen snprintf() und vsnprintf(). Ihr Zweck ist es, ein konsistentes Verhalten in Eckfällen zu gewährleisten, was die Standard-C-Funktionen nicht tun.

Die Wrapper stellen sicher, dass str[size-1] bei der Rückgabe immer '\0' ist. Sie schreiben nie mehr als size Bytes (einschließlich des abschließenden '\0') in str. Beide Funktionen erfordern, dass str != NULL, size > 0, format != NULL und size < INT_MAX. Beachten Sie, dass dies bedeutet, dass es kein Äquivalent zu C99 n = snprintf(NULL, 0, ...) gibt, das die benötigte Puffergröße ermitteln würde.

Der Rückgabewert (rv) für diese Funktionen sollte wie folgt interpretiert werden:

• Wenn 0 <= rv < size, war die Ausgabe-Konvertierung erfolgreich und rv Zeichen wurden nach str geschrieben (ohne das abschließende '\0'-Byte bei str[rv]).

• Wenn rv >= size, wurde die Ausgabe-Konvertierung gekürzt und ein Puffer mit rv + 1 Bytes wäre zum Erfolg erforderlich gewesen. str[size-1] ist in diesem Fall '\0'.

• Wenn rv < 0, "ist etwas Schlimmes passiert". str[size-1] ist auch in diesem Fall '\0', aber der Rest von str ist undefiniert. Die genaue Ursache des Fehlers hängt von der zugrundeliegenden Plattform ab.

Die folgenden Funktionen bieten lokalisierungsunabhängige String-zu-Zahl-Konvertierungen.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)

Teil der Stable ABI.

Konvertiert den Anfang der Zeichenkette in str in einen unsigned long-Wert gemäß der angegebenen base, die zwischen 2 und 36 (einschließlich) liegen muss oder den speziellen Wert 0 hat.

Führende Leerzeichen und Groß-/Kleinschreibung werden ignoriert. Wenn base Null ist, sucht es nach einem führenden 0b, 0o oder 0x, um die Basis zu bestimmen. Wenn diese fehlen, ist die Standardeinstellung 10. Die Basis muss 0 oder zwischen 2 und 36 (einschließlich) sein. Wenn ptr nicht NULL ist, enthält es einen Zeiger auf das Ende des Scans.

Wenn der konvertierte Wert den Bereich des entsprechenden Rückgabetyps verlässt, tritt ein Bereichsfehler auf (errno wird auf ERANGE gesetzt) und ULONG_MAX wird zurückgegeben. Wenn keine Konvertierung durchgeführt werden kann, wird 0 zurückgegeben.

Siehe auch die Unix-manpage strtoul(3).

Hinzugefügt in Version 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)

Teil der Stable ABI.

Konvertiert den Anfang der Zeichenkette in str in einen long-Wert gemäß der angegebenen base, die zwischen 2 und 36 (einschließlich) liegen muss oder den speziellen Wert 0 hat.

Gleich wie PyOS_strtoul(), gibt aber stattdessen einen long-Wert und bei Überläufen LONG_MAX zurück.

Siehe auch die Unix-manpage strtol(3).

Hinzugefügt in Version 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

Teil der Stable ABI.

Konvertiert eine Zeichenkette s in ein double und löst bei einem Fehler eine Python-Ausnahme aus. Die Menge der akzeptierten Zeichenketten entspricht der Menge der Zeichenketten, die vom float()-Konstruktor von Python akzeptiert werden, mit der Ausnahme, dass s keine führenden oder nachfolgenden Leerzeichen haben darf. Die Konvertierung ist unabhängig von der aktuellen Locale.

Wenn endptr NULL ist, wird die gesamte Zeichenkette konvertiert. Löst ValueError aus und gibt -1.0 zurück, wenn die Zeichenkette keine gültige Darstellung einer Gleitkommazahl ist.

Wenn endptr nicht NULL ist, wird so viel wie möglich von der Zeichenkette konvertiert und *endptr wird so gesetzt, dass es auf das erste nicht konvertierte Zeichen zeigt. Wenn kein Anfangssegment der Zeichenkette die gültige Darstellung einer Gleitkommazahl ist, wird *endptr so gesetzt, dass es auf den Anfang der Zeichenkette zeigt, ValueError ausgelöst und -1.0 zurückgegeben.

Wenn s einen Wert darstellt, der zu groß ist, um ihn in einem Float zu speichern (z. B. ist "1e500" auf vielen Plattformen eine solche Zeichenkette), dann gibt die Funktion Py_INFINITY (mit entsprechendem Vorzeichen) zurück und löst keine Ausnahme aus, wenn overflow_exception NULL ist. Andernfalls muss overflow_exception auf ein Python-Ausnahmeobjekt zeigen; löst diese Ausnahme aus und gibt -1.0 zurück. In beiden Fällen wird *endptr so gesetzt, dass es auf das erste Zeichen nach dem konvertierten Wert zeigt.

Wenn bei der Konvertierung ein anderer Fehler auftritt (z. B. ein Speicherfehler), wird die entsprechende Python-Ausnahme ausgelöst und -1.0 zurückgegeben.

Hinzugefügt in Version 3.1.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

Teil der Stable ABI.

Konvertiert einen double val in eine Zeichenkette unter Verwendung des angegebenen format_code, der precision und der flags.

format_code muss einer der Werte 'e', 'E', 'f', 'F', 'g', 'G' oder 'r' sein. Für 'r' muss die angegebene precision 0 sein und wird ignoriert. Der Formatcode 'r' gibt das Standardformat von repr() an.

flags können Null oder mehr der Werte Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0 oder Py_DTSF_ALT sein, die miteinander verknüpft sind.

• Py_DTSF_SIGN bedeutet, dass der zurückgegebene String immer mit einem Vorzeichen versehen wird, auch wenn val nicht negativ ist.

• Py_DTSF_ADD_DOT_0 bedeutet, dass sichergestellt wird, dass der zurückgegebene String nicht wie eine Ganzzahl aussieht.

• Py_DTSF_ALT bedeutet, dass „alternative“ Formatierungsregeln angewendet werden. Siehe die Dokumentation für den '#'-Spezifizierer von PyOS_snprintf() für Details.

Wenn ptype nicht NULL ist, dann wird der Wert, auf den er zeigt, auf einen der Werte Py_DTST_FINITE, Py_DTST_INFINITE oder Py_DTST_NAN gesetzt, was anzeigt, dass val eine endliche Zahl, eine unendliche Zahl oder keine Zahl ist.

Der Rückgabewert ist ein Zeiger auf buffer mit der konvertierten Zeichenkette oder NULL, wenn die Konvertierung fehlschlug. Der Aufrufer ist dafür verantwortlich, die zurückgegebene Zeichenkette durch Aufruf von PyMem_Free() freizugeben.

Hinzugefügt in Version 3.1.

int PyOS_stricmp(const char *s1, const char *s2)

Groß-/Kleinschreibungsunabhängiger Vergleich von Zeichenketten. Die Funktion funktioniert fast identisch wie strcmp(), ignoriert aber die Groß-/Kleinschreibung.

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

Groß-/Kleinschreibungsunabhängiger Vergleich von Zeichenketten. Die Funktion funktioniert fast identisch wie strncmp(), ignoriert aber die Groß-/Kleinschreibung.