Unicode-Objekte und Codecs¶

Unicode-Objekte¶

Seit der Implementierung von PEP 393 in Python 3.3 verwenden Unicode-Objekte intern verschiedene Darstellungen, um den vollständigen Bereich von Unicode-Zeichen zu handhaben und gleichzeitig speichereffizient zu bleiben. Es gibt Sonderfälle für Zeichenketten, bei denen alle Codepunkte kleiner als 128, 256 oder 65536 sind; andernfalls müssen die Codepunkte kleiner als 1114112 sein (was dem vollen Unicode-Bereich entspricht).

Die UTF-8-Darstellung wird bei Bedarf erstellt und im Unicode-Objekt zwischengespeichert.

Hinweis

Die Py_UNICODE-Darstellung wurde seit Python 3.12 mit veralteten APIs entfernt. Weitere Informationen finden Sie in PEP 623.

Unicode-Typ¶

Dies sind die grundlegenden Unicode-Objekttypen, die für die Unicode-Implementierung in Python verwendet werden.

PyTypeObject PyUnicode_Type¶: Teil der Stable ABI.
Diese Instanz von PyTypeObject repräsentiert den Python-Unicode-Typ. Sie wird für Python-Code als str verfügbar gemacht.

PyTypeObject PyUnicodeIter_Type¶: Teil der Stable ABI.
Diese Instanz von PyTypeObject repräsentiert den Python-Unicode-Iterator-Typ. Sie wird verwendet, um über Unicode-Zeichenkettenobjekte zu iterieren.

type Py_UCS4¶
type Py_UCS2¶
type Py_UCS1¶: Teil der Stable ABI.
Diese Typen sind Typedefs für vorzeichenlose Ganzzahltypen, die breit genug sind, um Zeichen mit 32, 16 und 8 Bits zu enthalten. Bei der Arbeit mit einzelnen Unicode-Zeichen sollte Py_UCS4 verwendet werden.

Hinzugefügt in Version 3.3.

type PyASCIIObject¶
type PyCompactUnicodeObject¶
type PyUnicodeObject¶: Diese Untertypen von PyObject repräsentieren ein Python-Unicode-Objekt. In fast allen Fällen sollten sie nicht direkt verwendet werden, da alle API-Funktionen, die mit Unicode-Objekten arbeiten, PyObject-Zeiger als Eingabe und Ausgabe nehmen.

Hinzugefügt in Version 3.3.

Die folgenden APIs sind C-Makros und statische Inline-Funktionen für schnelle Prüfungen und den Zugriff auf interne schreibgeschützte Daten von Unicode-Objekten.

int PyUnicode_Check(PyObject *obj)¶: Gibt wahr zurück, wenn das Objekt obj ein Unicode-Objekt oder eine Instanz eines Unicode-Subtyps ist. Diese Funktion ist immer erfolgreich.

int PyUnicode_CheckExact(PyObject *obj)¶: Gibt wahr zurück, wenn das Objekt obj ein Unicode-Objekt, aber keine Instanz eines Subtyps ist. Diese Funktion ist immer erfolgreich.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶: Gibt die Länge der Unicode-Zeichenkette in Codepunkten zurück. unicode muss ein Unicode-Objekt in der "kanonischen" Darstellung sein (nicht geprüft).

Hinzugefügt in Version 3.3.

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)¶
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)¶
Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)¶: Gibt einen Zeiger auf die kanonische Darstellung zurück, der in UCS1-, UCS2- oder UCS4-Ganzzahltypen für direkten Zeichenzugriff umgewandelt wurde. Es werden keine Prüfungen durchgeführt, ob die kanonische Darstellung die korrekte Zeichengröße hat; verwenden Sie PyUnicode_KIND(), um die richtige Funktion auszuwählen.

Hinzugefügt in Version 3.3.

PyUnicode_1BYTE_KIND¶
PyUnicode_2BYTE_KIND¶
PyUnicode_4BYTE_KIND¶: Rückgabewerte des Makros PyUnicode_KIND().

Hinzugefügt in Version 3.3.

Geändert in Version 3.12: PyUnicode_WCHAR_KIND wurde entfernt.

int PyUnicode_KIND(PyObject *unicode)¶: Gibt eine der PyUnicode-Konstanten (siehe oben) zurück, die angeben, wie viele Bytes pro Zeichen dieses Unicode-Objekt zur Speicherung seiner Daten verwendet. unicode muss ein Unicode-Objekt in der "kanonischen" Darstellung sein (nicht geprüft).

Hinzugefügt in Version 3.3.

void *PyUnicode_DATA(PyObject *unicode)¶: Gibt einen Zeiger vom Typ `void` auf den rohen Unicode-Puffer zurück. unicode muss ein Unicode-Objekt in der "kanonischen" Darstellung sein (nicht geprüft).

Hinzugefügt in Version 3.3.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)¶

Schreibt den Codepunkt value an den angegebenen nullbasierten index in einer Zeichenkette.

Der kind-Wert und der data-Zeiger müssen aus einer Zeichenkette mit PyUnicode_KIND() und PyUnicode_DATA() abgerufen worden sein. Sie müssen eine Referenz auf diese Zeichenkette halten, während Sie PyUnicode_WRITE() aufrufen. Alle Anforderungen von PyUnicode_WriteChar() gelten ebenfalls.

Die Funktion führt keine Prüfungen für ihre Anforderungen durch und ist für die Verwendung in Schleifen vorgesehen.

Hinzugefügt in Version 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶: Liest einen Codepunkt aus einer kanonischen Darstellung data (wie mit PyUnicode_DATA() erhalten). Es werden keine Prüfungen oder Bereitschaftsabrufe durchgeführt.

Hinzugefügt in Version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶: Liest ein Zeichen aus einem Unicode-Objekt unicode, das in der "kanonischen" Darstellung vorliegen muss. Dies ist weniger effizient als PyUnicode_READ(), wenn Sie mehrere aufeinanderfolgende Lesevorgänge durchführen.

Hinzugefügt in Version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶: Gibt den maximalen Codepunkt zurück, der geeignet ist, eine weitere Zeichenkette basierend auf unicode zu erstellen, welche in der "kanonischen" Darstellung vorliegen muss. Dies ist immer eine Annäherung, aber effizienter als das Iterieren über die Zeichenkette.

Hinzugefügt in Version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)¶: Teil der Stable ABI.
Gibt 1 zurück, wenn die Zeichenkette ein gültiger Bezeichner gemäß der Sprachdefinition ist, Abschnitt Namen (Bezeichner und Schlüsselwörter). Gibt andernfalls 0 zurück.

Geändert in Version 3.9: Die Funktion ruft Py_FatalError() nicht mehr auf, wenn die Zeichenkette nicht bereit ist.

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)¶: Gibt wahr zurück, wenn die Zeichenkette nur ASCII-Zeichen enthält. Entspricht str.isascii().

Hinzugefügt in Version 3.2.

Unicode-Zeicheneigenschaften¶

Unicode bietet viele verschiedene Zeicheneigenschaften. Die am häufigsten benötigten sind über diese Makros verfügbar, die je nach Python-Konfiguration auf C-Funktionen abgebildet werden.

int Py_UNICODE_ISSPACE(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein Leerzeichen ist.

int Py_UNICODE_ISLOWER(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein Kleinbuchstabe ist.

int Py_UNICODE_ISUPPER(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein Großbuchstabe ist.

int Py_UNICODE_ISTITLE(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein Titelbuchstabe ist.

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein Zeilenumbruchzeichen ist.

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch eine Dezimalzahl ist.

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch eine Ziffer ist.

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch eine numerische Zeichen ist.

int Py_UNICODE_ISALPHA(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein Buchstabe ist.

int Py_UNICODE_ISALNUM(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein alphanumerisches Zeichen ist.

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)¶: Gibt 1 oder 0 zurück, je nachdem, ob ch ein druckbares Zeichen im Sinne von str.isprintable() ist.

Diese APIs können für schnelle direkte Zeichenkonvertierungen verwendet werden.

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)¶: Gibt das Zeichen ch in Kleinbuchstaben konvertiert zurück.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)¶: Gibt das Zeichen ch in Großbuchstaben konvertiert zurück.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)¶: Gibt das Zeichen ch in Titelbuchstaben konvertiert zurück.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)¶: Gibt das Zeichen ch in eine positive Dezimalzahl konvertiert zurück. Gibt -1 zurück, wenn dies nicht möglich ist. Diese Funktion löst keine Ausnahmen aus.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶: Gibt das Zeichen ch in eine einzelne Ziffer konvertiert zurück. Gibt -1 zurück, wenn dies nicht möglich ist. Diese Funktion löst keine Ausnahmen aus.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶: Gibt das Zeichen ch in eine Gleitkommazahl konvertiert zurück. Gibt -1.0 zurück, wenn dies nicht möglich ist. Diese Funktion löst keine Ausnahmen aus.

Diese APIs können zur Arbeit mit Surrogaten verwendet werden.

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)¶: Prüft, ob ch ein Surrogat ist (0xD800 <= ch <= 0xDFFF).

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)¶: Prüft, ob ch ein hohes Surrogat ist (0xD800 <= ch <= 0xDBFF).

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)¶: Prüft, ob ch ein tiefes Surrogat ist (0xDC00 <= ch <= 0xDFFF).

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)¶: Verknüpft zwei Surrogat-Codepunkte und gibt einen einzelnen Py_UCS4-Wert zurück. high und low sind jeweils das führende und nachfolgende Surrogat in einem Surrogatpaar. high muss im Bereich [0xD800; 0xDBFF] und low muss im Bereich [0xDC00; 0xDFFF] liegen.

Erstellen und Zugreifen auf Unicode-Zeichenketten¶

Um Unicode-Objekte zu erstellen und auf ihre grundlegenden Sequenzeigenschaften zuzugreifen, verwenden Sie diese APIs.

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶

Rückgabewert: Neue Referenz.

Erstellt ein neues Unicode-Objekt. maxchar sollte der tatsächliche maximale Codepunkt sein, der in die Zeichenkette eingefügt werden soll. Als Annäherung kann er auf den nächsten Wert in der Sequenz 127, 255, 65535, 1114111 aufgerundet werden.

Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Nach der Erstellung kann die Zeichenkette mit PyUnicode_WriteChar(), PyUnicode_CopyCharacters(), PyUnicode_Fill(), PyUnicode_WRITE() oder ähnlichem gefüllt werden. Da Zeichenketten unveränderlich sein sollen, achten Sie darauf, das Ergebnis nicht zu "verwenden", während es modifiziert wird. Insbesondere bevor es mit seinen endgültigen Inhalten gefüllt ist, muss eine Zeichenkette:

darf nicht gehasht werden,
darf nicht zu UTF-8 oder einer anderen nicht-"kanonischen" Darstellung konvertiert werden,


darf ihre Referenzanzahl nicht geändert werden,
darf nicht mit Code geteilt werden, der eines der oben genannten tun könnte.


Diese Liste ist nicht vollständig. Es liegt in Ihrer Verantwortung, diese Verwendungszwecke zu vermeiden; Python prüft diese Anforderungen nicht immer.
Um zu vermeiden, dass versehentlich ein teilweise geschriebenes String-Objekt preisgegeben wird, verwenden Sie vorzugsweise die API PyUnicodeWriter oder eine der unten aufgeführten PyUnicode_From* Funktionen.

Hinzugefügt in Version 3.3.





PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)¶

Rückgabewert: Neue Referenz.Erstellt ein neues Unicode-Objekt mit der angegebenen kind (mögliche Werte sind PyUnicode_1BYTE_KIND usw., wie von PyUnicode_KIND() zurückgegeben). Der buffer muss auf ein Array von size Einheiten mit 1, 2 oder 4 Bytes pro Zeichen zeigen, wie durch die Art vorgegeben.
Falls erforderlich, wird der Eingabe-buffer kopiert und in die kanonische Darstellung umgewandelt. Wenn der buffer beispielsweise ein UCS4-String ist (PyUnicode_4BYTE_KIND) und nur Codepunkte im UCS1-Bereich enthält, wird er in UCS1 (PyUnicode_1BYTE_KIND) umgewandelt.

Hinzugefügt in Version 3.3.





PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt aus dem char-Puffer str. Die Bytes werden als UTF-8-kodiert interpretiert. Der Puffer wird in das neue Objekt kopiert. Der Rückgabewert kann ein geteiltes Objekt sein, d. h. eine Modifikation der Daten ist nicht erlaubt.
Diese Funktion löst SystemError aus, wenn

size < 0,
str ist NULL und size > 0


Geändert in Version 3.12: str == NULL mit size > 0 ist nicht mehr erlaubt.





PyObject *PyUnicode_FromString(const char *str)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt aus einem UTF-8-kodierten, nullterminierten char-Puffer str.




PyObject *PyUnicode_FromFormat(const char *format, ...)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Nimmt einen C printf()-ähnlichen format-String und eine variable Anzahl von Argumenten, berechnet die Größe des resultierenden Python-Unicode-Strings und gibt einen String mit den formatierten Werten zurück. Die variablen Argumente müssen C-Typen sein und exakt den Formatzeichen im ASCII-kodierten format-String entsprechen.
Ein Konvertierungsspezifizierer besteht aus zwei oder mehr Zeichen und hat folgende Komponenten, die in dieser Reihenfolge auftreten müssen:

Das Zeichen '%', das den Beginn des Spezifizierers markiert.
Konvertierungsflags (optional), die das Ergebnis einiger Konvertierungstypen beeinflussen.
Mindestfeldbreite (optional). Wenn als '*' (Sternchen) angegeben, wird die tatsächliche Breite im nächsten Argument angegeben, das vom Typ int sein muss, und das zu konvertierende Objekt kommt nach der Mindestfeldbreite und der optionalen Präzision.
Präzision (optional), angegeben als ein '.' (Punkt) gefolgt von der Präzision. Wenn als '*' (ein Sternchen) angegeben, wird die tatsächliche Präzision im nächsten Argument angegeben, das vom Typ int sein muss, und der zu konvertierende Wert kommt nach der Präzision.
Längenmodifikator (optional).
Konvertierungstyp.

Die Konvertierungsflag-Zeichen sind


Flag
Bedeutung



0
Der Wert wird für numerische Werte mit Nullen aufgefüllt.

-
Der konvertierte Wert ist linksbündig ausgerichtet (überschreibt das 0-Flag, wenn beide angegeben sind).



Die Längenmodifikatoren für folgende Ganzzahlkonvertierungen (d, i, o, u, x oder X) geben den Typ des Arguments an (standardmäßig int)


Modifikator
Typen



l
long oder unsigned long

ll
long long oder unsigned long long

j
intmax_t oder uintmax_t

z
size_t oder ssize_t

t
ptrdiff_t



Der Längenmodifikator l für folgende Konvertierungen s oder V gibt an, dass der Typ des Arguments const wchar_t* ist.
Die Konvertierungsspezifizierer sind


Konvertierungsspezifizierer
Typ
Kommentar



%
n/a
Das literale Zeichen %.

d, i
Angegeben durch den Längenmodifikator
Die Dezimaldarstellung einer vorzeichenbehafteten C-Ganzzahl.

u
Angegeben durch den Längenmodifikator
Die Dezimaldarstellung einer vorzeichenlosen C-Ganzzahl.

o
Angegeben durch den Längenmodifikator
Die Oktaldarstellung einer vorzeichenlosen C-Ganzzahl.

x
Angegeben durch den Längenmodifikator
Die Hexadezimaldarstellung einer vorzeichenlosen C-Ganzzahl (Kleinbuchstaben).

X
Angegeben durch den Längenmodifikator
Die Hexadezimaldarstellung einer vorzeichenlosen C-Ganzzahl (Großbuchstaben).

c
int
Ein einzelnes Zeichen.

s
const char* oder const wchar_t*
Ein nullterminiertes C-Zeichenarray.

p
const void*
Die Hex-Darstellung eines C-Zeigers. Weitgehend äquivalent zu printf("%p"), außer dass garantiert wird, dass es mit dem Literal 0x beginnt, unabhängig davon, was die printf des Systems liefert.

A
PyObject*
Das Ergebnis des Aufrufs von ascii().

U
PyObject*
Ein Unicode-Objekt.

V
PyObject*, const char* oder const wchar_t*
Ein Unicode-Objekt (das NULL sein kann) und ein nullterminiertes C-Zeichenarray als zweiter Parameter (das verwendet wird, wenn der erste Parameter NULL ist).

S
PyObject*
Das Ergebnis des Aufrufs von PyObject_Str().

R
PyObject*
Das Ergebnis des Aufrufs von PyObject_Repr().

T
PyObject*
Ruft den vollständig qualifizierten Namen eines Objekttyps ab; ruft PyType_GetFullyQualifiedName() auf.

#T
PyObject*
Ähnlich dem T-Format, verwendet jedoch einen Doppelpunkt (:) als Trennzeichen zwischen dem Modulnamen und dem qualifizierten Namen.

N
PyTypeObject*
Ruft den vollständig qualifizierten Namen eines Typs ab; ruft PyType_GetFullyQualifiedName() auf.

#N
PyTypeObject*
Ähnlich dem N-Format, verwendet jedoch einen Doppelpunkt (:) als Trennzeichen zwischen dem Modulnamen und dem qualifizierten Namen.




Hinweis
Die Einheit der Breitenformatierung ist die Anzahl der Zeichen und nicht die Anzahl der Bytes. Die Einheit der Präzisionsformatierung ist die Anzahl der Bytes oder wchar_t-Elemente (wenn der Längenmodifikator l verwendet wird) für "%s" und "%V" (wenn das PyObject*-Argument NULL ist) und eine Anzahl von Zeichen für "%A", "%U", "%S", "%R" und "%V" (wenn das PyObject*-Argument nicht NULL ist).


Hinweis
Im Gegensatz zu C printf() hat das 0-Flag auch dann eine Auswirkung, wenn für Ganzzahlkonvertierungen (d, i, u, o, x oder X) eine Präzision angegeben ist.


Geändert in Version 3.2: Unterstützung für "%lld" und "%llu" hinzugefügt.


Geändert in Version 3.3: Unterstützung für "%li", "%lli" und "%zi" hinzugefügt.


Geändert in Version 3.4: Unterstützung für Breiten- und Präzisionsformatierer für "%s", "%A", "%U", "%V", "%S", "%R" hinzugefügt.


Geändert in Version 3.12: Unterstützung für Konvertierungsspezifizierer o und X. Unterstützung für Längenmodifikatoren j und t. Längenmodifikatoren werden nun auf alle Ganzzahlkonvertierungen angewendet. Längenmodifikator l wird nun auf Konvertierungsspezifizierer s und V angewendet. Unterstützung für variable Breiten und Präzisionen *. Unterstützung für das Flag -.
Ein nicht erkannter Formatbuchstabe löst nun eine SystemError aus. In früheren Versionen wurde der Rest des Formatstrings unverändert in den Ergebnisstring kopiert und alle zusätzlichen Argumente verworfen.


Geändert in Version 3.13: Unterstützung für die Formate %T, %#T, %N und %#N hinzugefügt.





PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Identisch mit PyUnicode_FromFormat(), außer dass es genau zwei Argumente entgegennimmt.




PyObject *PyUnicode_FromObject(PyObject *obj)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kopiert eine Instanz eines Unicode-Subtyps in ein neues echtes Unicode-Objekt, falls erforderlich. Wenn obj bereits ein echtes Unicode-Objekt (kein Subtyp) ist, wird eine neue starke Referenz auf das Objekt zurückgegeben.
Objekte, die keine Unicode-Objekte oder deren Subtypen sind, führen zu einer TypeError.




PyObject *PyUnicode_FromOrdinal(int ordinal)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt aus dem angegebenen Unicode-Codepunkt-ordinal.
Das Ordinal muss im Bereich range(0x110000) liegen. Bei einem Verstoß wird eine ValueError ausgelöst.




PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Dekodiert ein kodiertes Objekt obj in ein Unicode-Objekt.
bytes, bytearray und andere bytes-ähnliche Objekte werden gemäß der angegebenen encoding und unter Verwendung der von errors definierten Fehlerbehandlung dekodiert. Beides kann NULL sein, damit die Schnittstelle die Standardwerte verwendet (siehe Built-in Codecs für Details).
Alle anderen Objekte, einschließlich Unicode-Objekte, führen dazu, dass eine TypeError gesetzt wird.
Die API gibt NULL zurück, wenn ein Fehler aufgetreten ist. Der Aufrufer ist dafür verantwortlich, die zurückgegebenen Objekte zu decrefizieren.




void PyUnicode_Append(PyObject **p_left, PyObject *right)¶

Teil der Stable ABI.Hängt den String right an das Ende von p_left an. p_left muss auf eine starke Referenz auf ein Unicode-Objekt zeigen; PyUnicode_Append() gibt diese Referenz frei („stiehlt“ sie).
Bei einem Fehler wird *p_left auf NULL gesetzt und eine Ausnahme ausgelöst.
Bei Erfolg wird *p_left auf eine neue starke Referenz auf das Ergebnis gesetzt.




void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)¶

Teil der Stable ABI.Die Funktion ähnelt PyUnicode_Append(), wobei der einzige Unterschied darin besteht, dass sie die Referenzanzahl von right um eins verringert.




PyObject *PyUnicode_BuildEncodingMap(PyObject *string)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Gibt eine Abbildung zurück, die für die Dekodierung einer benutzerdefinierten einbyteigen Kodierung geeignet ist. Bei einem Unicode-String string von bis zu 256 Zeichen, der eine Kodierungstabelle darstellt, wird entweder ein kompaktes internes Abbildungsobjekt oder ein Dictionary zurückgegeben, das Zeichenordinale auf Byte-Werte abbildet. Löst eine TypeError aus und gibt NULL bei ungültiger Eingabe zurück.

Hinzugefügt in Version 3.2.





const char *PyUnicode_GetDefaultEncoding(void)¶

Teil der Stable ABI.Gibt den Namen der Standard-String-Kodierung, "utf-8", zurück. Siehe sys.getdefaultencoding().
Der zurückgegebene String muss nicht freigegeben werden und ist bis zur Beendigung des Interpreters gültig.




Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶

Teil der Stable ABI seit Version 3.7.Gibt die Länge des Unicode-Objekts in Codepunkten zurück.
Bei einem Fehler wird eine Ausnahme gesetzt und -1 zurückgegeben.

Hinzugefügt in Version 3.3.





Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)¶

Kopiert Zeichen von einem Unicode-Objekt in ein anderes. Diese Funktion führt bei Bedarf Zeichenkonvertierungen durch und greift nach Möglichkeit auf memcpy() zurück. Gibt -1 zurück und setzt eine Ausnahme bei einem Fehler, gibt andernfalls die Anzahl der kopierten Zeichen zurück.
Der String darf noch nicht „verwendet“ worden sein. Siehe PyUnicode_New() für Details.

Hinzugefügt in Version 3.3.





int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);¶

Teil der Stable ABI.Ändert die Größe eines Unicode-Objekts *unicode auf die neue length in Codepunkten.
Versucht, den String vor Ort zu vergrößern (was normalerweise schneller ist, als einen neuen String zu allozieren und Zeichen zu kopieren) oder erstellt einen neuen String.
*unicode wird so geändert, dass es auf das neue (geänderte) Objekt zeigt und bei Erfolg 0 zurückgegeben wird. Andernfalls wird -1 zurückgegeben, eine Ausnahme wird gesetzt und *unicode bleibt unverändert.
Die Funktion prüft nicht den Stringinhalt, das Ergebnis ist möglicherweise keine Zeichenkette in kanonischer Darstellung.




Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)¶

Füllt einen String mit einem Zeichen: schreibt fill_char in unicode[start:start+length].
Schlägt fehl, wenn fill_char größer als das maximale Zeichen des Strings ist oder wenn der String mehr als 1 Referenz hat.
Der String darf noch nicht „verwendet“ worden sein. Siehe PyUnicode_New() für Details.
Gibt die Anzahl der geschriebenen Zeichen zurück oder gibt -1 zurück und löst im Fehlerfall eine Ausnahme aus.

Hinzugefügt in Version 3.3.





int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)¶

Teil der Stable ABI seit Version 3.7.Schreibt ein character in den String unicode an den nullbasierten index. Gibt 0 bei Erfolg zurück, -1 bei Fehler mit gesetzter Ausnahme.
Diese Funktion prüft, ob unicode ein Unicode-Objekt ist, ob der Index nicht außerhalb der Grenzen liegt und ob die Referenzanzahl des Objekts eins ist. Siehe PyUnicode_WRITE() für eine Version, die diese Prüfungen überspringt und sie zu Ihrer Verantwortung macht.
Der String darf noch nicht „verwendet“ worden sein. Siehe PyUnicode_New() für Details.

Hinzugefügt in Version 3.3.





Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶

Teil der Stable ABI seit Version 3.7.Liest ein Zeichen aus einem String. Diese Funktion prüft, ob unicode ein Unicode-Objekt ist und der Index nicht außerhalb der Grenzen liegt, im Gegensatz zu PyUnicode_READ_CHAR(), das keine Fehlerprüfung durchführt.
Gibt das Zeichen bei Erfolg zurück, bei einem Fehler mit gesetzter Ausnahme -1.

Hinzugefügt in Version 3.3.





PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI seit Version 3.7.Gibt einen Teilstring von unicode zurück, vom Zeichenindex start (inklusive) bis zum Zeichenindex end (exklusive). Negative Indizes werden nicht unterstützt. Bei einem Fehler wird eine Ausnahme gesetzt und NULL zurückgegeben.

Hinzugefügt in Version 3.3.





Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶

Teil der Stable ABI seit Version 3.7.Kopiert den String unicode in einen UCS4-Buffer, einschließlich eines Nullzeichens, wenn copy_null gesetzt ist. Gibt NULL zurück und setzt eine Ausnahme bei einem Fehler (insbesondere eine SystemError, wenn buflen kleiner als die Länge von unicode ist). buffer wird bei Erfolg zurückgegeben.

Hinzugefügt in Version 3.3.





Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶

Teil der Stable ABI seit Version 3.7.Kopiert den String unicode in einen neuen UCS4-Buffer, der mit PyMem_Malloc() alloziert wird. Wenn dies fehlschlägt, wird NULL mit einer gesetzten MemoryError zurückgegeben. Der zurückgegebene Buffer hat immer einen zusätzlichen Null-Codepoint angehängt.

Hinzugefügt in Version 3.3.



Locale-Kodierung¶
Die aktuelle Locale-Kodierung kann verwendet werden, um Text vom Betriebssystem zu dekodieren.


PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI seit Version 3.7.Dekodiert einen String von UTF-8 unter Android und VxWorks oder von der aktuellen Locale-Kodierung auf anderen Plattformen. Die unterstützten Fehlerbehandler sind "strict" und "surrogateescape" (PEP 383). Der Dekoder verwendet den Fehlerbehandler "strict", wenn errors NULL ist. str muss mit einem Nullzeichen enden, darf aber keine eingebetteten Nullzeichen enthalten.
Verwenden Sie PyUnicode_DecodeFSDefaultAndSize(), um einen String von der Dateisystemkodierung und dem Fehlerbehandler zu dekodieren.
Diese Funktion ignoriert den Python UTF-8-Modus.

Siehe auch
Die Funktion Py_DecodeLocale().


Hinzugefügt in Version 3.3.


Geändert in Version 3.7: Die Funktion verwendet nun auch die aktuelle Locale-Kodierung für den Fehlerbehandler surrogateescape, außer unter Android. Zuvor wurde Py_DecodeLocale() für surrogateescape und die aktuelle Locale-Kodierung für strict verwendet.





PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI seit Version 3.7.Ähnlich wie PyUnicode_DecodeLocaleAndSize(), aber die Stringlänge wird mit strlen() berechnet.

Hinzugefügt in Version 3.3.





PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI seit Version 3.7.Kodiert ein Unicode-Objekt zu UTF-8 unter Android und VxWorks oder zur aktuellen Locale-Kodierung auf anderen Plattformen. Die unterstützten Fehlerbehandler sind "strict" und "surrogateescape" (PEP 383). Der Kodierer verwendet den Fehlerbehandler "strict", wenn errors NULL ist. Gibt ein bytes-Objekt zurück. unicode darf keine eingebetteten Nullzeichen enthalten.
Verwenden Sie PyUnicode_EncodeFSDefault(), um einen String in die Dateisystemkodierung und den Fehlerbehandler zu kodieren.
Diese Funktion ignoriert den Python UTF-8-Modus.

Siehe auch
Die Funktion Py_EncodeLocale().


Hinzugefügt in Version 3.3.


Geändert in Version 3.7: Die Funktion verwendet nun auch die aktuelle Locale-Kodierung für den Fehlerbehandler surrogateescape, außer unter Android. Zuvor wurde Py_EncodeLocale() für surrogateescape und die aktuelle Locale-Kodierung für strict verwendet.





Dateisystem-Kodierung¶
Funktionen zum Kodieren von und Dekodieren von der Dateisystemkodierung und dem Fehlerbehandler (PEP 383 und PEP 529).
Um Dateinamen beim Parsen von Argumenten in bytes zu kodieren, sollte der Konverter "O&" verwendet werden, wobei PyUnicode_FSConverter() als Konvertierungsfunktion übergeben wird.


int PyUnicode_FSConverter(PyObject *obj, void *result)¶

Teil der Stable ABI.PyArg_Parse* Konverter: kodiert str-Objekte – direkt oder über die os.PathLike-Schnittstelle erhalten – in bytes unter Verwendung von PyUnicode_EncodeFSDefault(); bytes-Objekte werden unverändert ausgegeben. result muss die Adresse einer C-Variablen vom Typ PyObject* (oder PyBytesObject*) sein. Bei Erfolg wird die Variable auf eine neue starke Referenz auf ein bytes-Objekt gesetzt, das freigegeben werden muss, wenn es nicht mehr verwendet wird, und ein von Null verschiedener Wert zurückgegeben (Py_CLEANUP_SUPPORTED). Eingebettete Null-Bytes sind im Ergebnis nicht erlaubt. Bei einem Fehler wird 0 zurückgegeben und eine Ausnahme gesetzt.
Wenn obj NULL ist, gibt die Funktion eine starke Referenz, die in der durch result referenzierten Variable gespeichert ist, frei und gibt 1 zurück.

Hinzugefügt in Version 3.1.


Geändert in Version 3.6: Akzeptiert ein pfadähnliches Objekt.



Um Dateinamen beim Parsen von Argumenten in str zu dekodieren, sollte der Konverter "O&" verwendet werden, wobei PyUnicode_FSDecoder() als Konvertierungsfunktion übergeben wird.


int PyUnicode_FSDecoder(PyObject *obj, void *result)¶

Teil der Stable ABI.PyArg_Parse* Konverter: dekodiert bytes-Objekte – entweder direkt oder indirekt über die os.PathLike-Schnittstelle erhalten – in str unter Verwendung von PyUnicode_DecodeFSDefaultAndSize(); str-Objekte werden als-is ausgegeben. result muss die Adresse einer C-Variablen vom Typ PyObject* (oder PyUnicodeObject*) sein. Bei Erfolg wird die Variable auf eine neue starke Referenz auf ein Unicode-Objekt gesetzt, das freigegeben werden muss, wenn es nicht mehr verwendet wird, und ein von Null verschiedener Wert zurückgegeben (Py_CLEANUP_SUPPORTED). Eingebettete Nullzeichen sind im Ergebnis nicht erlaubt. Bei einem Fehler wird 0 zurückgegeben und eine Ausnahme gesetzt.
Wenn obj NULL ist, gibt die Funktion die starke Referenz auf das Objekt, auf das durch result verwiesen wird, frei und gibt 1 zurück.

Hinzugefügt in Version 3.2.


Geändert in Version 3.6: Akzeptiert ein pfadähnliches Objekt.





PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Dekodiert einen String von der Dateisystemkodierung und dem Fehlerbehandler.
Wenn Sie einen String von der aktuellen Locale-Kodierung dekodieren müssen, verwenden Sie PyUnicode_DecodeLocaleAndSize().

Siehe auch
Die Funktion Py_DecodeLocale().


Geändert in Version 3.6: Der Dateisystem-Fehlerbehandler wird jetzt verwendet.





PyObject *PyUnicode_DecodeFSDefault(const char *str)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Dekodiert einen Null-terminierten String von der Dateisystemkodierung und dem Fehlerbehandler.
Wenn die Stringlänge bekannt ist, verwenden Sie PyUnicode_DecodeFSDefaultAndSize().

Geändert in Version 3.6: Der Dateisystem-Fehlerbehandler wird jetzt verwendet.





PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt in die Dateisystemkodierung und den Fehlerbehandler und gibt bytes zurück. Beachten Sie, dass das resultierende bytes-Objekt Null-Bytes enthalten kann.
Wenn Sie einen String in die aktuelle Locale-Kodierung kodieren müssen, verwenden Sie PyUnicode_EncodeLocale().

Siehe auch
Die Funktion Py_EncodeLocale().


Hinzugefügt in Version 3.2.


Geändert in Version 3.6: Der Dateisystem-Fehlerbehandler wird jetzt verwendet.





wchar_t-Unterstützung¶
wchar_t-Unterstützung für Plattformen, die sie unterstützen.


PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt aus dem wchar_t-Buffer wstr der gegebenen Größe. Die Übergabe von -1 als Größe bedeutet, dass die Funktion die Länge selbst berechnen muss, indem sie wcslen() verwendet. Gibt bei einem Fehler NULL zurück.




Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)¶

Teil der Stable ABI.Kopiert den Inhalt des Unicode-Objekts in den wchar_t-Buffer wstr. Es werden maximal size wchar_t-Zeichen kopiert (ohne ein möglicherweise nachfolgendes Nullterminierungszeichen). Gibt die Anzahl der kopierten wchar_t-Zeichen zurück oder im Fehlerfall -1.
Wenn wstr NULL ist, wird stattdessen die benötigte Größe zurückgegeben, um den gesamten Inhalt von unicode einschließlich einer terminierenden Null zu speichern.
Beachten Sie, dass der resultierende wchar_t* String möglicherweise null-terminiert ist oder auch nicht. Es liegt in der Verantwortung des Aufrufers sicherzustellen, dass der wchar_t*-String null-terminiert ist, falls dies von der Anwendung benötigt wird. Beachten Sie auch, dass der wchar_t*-String Nullzeichen enthalten kann, was dazu führen würde, dass der String bei Verwendung mit den meisten C-Funktionen abgeschnitten wird.




wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)¶

Teil der Stable ABI seit Version 3.7.Konvertiert das Unicode-Objekt in einen Wide-Character-String. Der Ausgabestring endet immer mit einem Nullzeichen. Wenn size nicht NULL ist, wird die Anzahl der Wide-Characters (ohne das abschließende Nullterminierungszeichen) in *size geschrieben. Beachten Sie, dass der resultierende wchar_t-String Nullzeichen enthalten kann, was dazu führt, dass der String bei Verwendung mit den meisten C-Funktionen abgeschnitten wird. Wenn size NULL ist und der wchar_t*-String Nullzeichen enthält, wird eine ValueError ausgelöst.
Gibt bei Erfolg einen von PyMem_New allozierten Buffer zurück (verwenden Sie PyMem_Free(), um ihn freizugeben). Bei einem Fehler gibt es NULL zurück und *size ist undefiniert. Löst eine MemoryError aus, wenn die Speicherzuweisung fehlschlägt.

Hinzugefügt in Version 3.2.


Geändert in Version 3.7: Löst eine ValueError aus, wenn size NULL ist und der wchar_t*-String Nullzeichen enthält.



Integrierte Codecs¶
Python bietet eine Reihe von integrierten Codecs, die für Geschwindigkeit in C geschrieben sind. Alle diese Codecs sind direkt über die folgenden Funktionen nutzbar.
Viele der folgenden APIs nehmen die beiden Argumente encoding und errors und haben die gleiche Semantik wie die des integrierten Konstruktors des String-Objekts str().
Das Setzen von encoding auf NULL bewirkt die Verwendung der Standardkodierung, die UTF-8 ist. Die Dateisystemaufrufe sollten PyUnicode_FSConverter() zur Kodierung von Dateinamen verwenden. Dies verwendet intern die Dateisystemkodierung und den Fehlerbehandler.
Die Fehlerbehandlung wird durch errors festgelegt, die auch auf NULL gesetzt werden kann, was bedeutet, dass die für den Codec definierte Standardbehandlung verwendet wird. Die Standardfehlerbehandlung für alle integrierten Codecs ist "strict" (ValueError wird ausgelöst).
Die Codecs verwenden alle eine ähnliche Schnittstelle. Nur Abweichungen von den folgenden generischen werden der Einfachheit halber dokumentiert.

Generische Codecs¶
Das folgende Makro ist bereitgestellt:


Py_UNICODE_REPLACEMENT_CHARACTER¶

Der Unicode-Codepoint U+FFFD (Ersetzungszeichen).
Dieses Unicode-Zeichen wird als Ersetzungszeichen beim Dekodieren verwendet, wenn das Argument errors auf "replace" gesetzt ist.


Dies sind die generischen Codec-APIs:


PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodieren von size Bytes des kodierten Strings str. encoding und errors haben die gleiche Bedeutung wie die Parameter mit denselben Namen im integrierten Funktionskonstruktor str(). Der zu verwendende Codec wird über die Python-Codec-Registry nachgeschlagen. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde.




PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt und gibt das Ergebnis als Python-Bytes-Objekt zurück. encoding und errors haben die gleiche Bedeutung wie die Parameter mit denselben Namen in der Unicode-Methode encode(). Der zu verwendende Codec wird über die Python-Codec-Registry nachgeschlagen. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde.




UTF-8-Codecs¶
Dies sind die UTF-8-Codec-APIs.


PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des UTF-8-kodierten Strings str. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Wenn consumed NULL ist, verhält es sich wie PyUnicode_DecodeUTF8(). Wenn consumed nicht NULL ist, werden nachfolgende unvollständige UTF-8-Byte-Sequenzen nicht als Fehler behandelt. Diese Bytes werden nicht dekodiert und die Anzahl der dekodierten Bytes wird in consumed gespeichert.




PyObject *PyUnicode_AsUTF8String(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt mit UTF-8 und gibt das Ergebnis als Python-Byte-Objekt zurück. Die Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.
Die Funktion schlägt fehl, wenn der String Surrogat-Codepunkte enthält (U+D800 - U+DFFF).




const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)¶

Teil der Stable ABI seit Version 3.10.Gibt einen Zeiger auf die UTF-8-Kodierung des Unicode-Objekts zurück und speichert die Größe der kodierten Darstellung (in Bytes) in size. Das Argument size kann NULL sein; in diesem Fall wird keine Größe gespeichert. Der zurückgegebene Puffer hat immer ein zusätzliches Null-Byte angehängt (nicht in size enthalten), unabhängig davon, ob andere Null-Codepunkte vorhanden sind.
Bei einem Fehler wird eine Ausnahme gesetzt, size auf -1 gesetzt (falls es nicht NULL ist) und NULL zurückgegeben.
Die Funktion schlägt fehl, wenn der String Surrogat-Codepunkte enthält (U+D800 - U+DFFF).
Diese Funktion cacht die UTF-8-Darstellung des Strings im Unicode-Objekt, und nachfolgende Aufrufe geben einen Zeiger auf denselben Puffer zurück. Der Aufrufer ist nicht für die Freigabe des Puffers verantwortlich. Der Puffer wird freigegeben und Zeiger darauf werden ungültig, wenn das Unicode-Objekt vom Garbage Collector gesammelt wird.

Hinzugefügt in Version 3.3.


Geändert in Version 3.7: Der Rückgabetyp ist jetzt const char * anstelle von char *.


Geändert in Version 3.10: Diese Funktion ist Teil der begrenzten API.





const char *PyUnicode_AsUTF8(PyObject *unicode)¶

Wie PyUnicode_AsUTF8AndSize(), aber speichert die Größe nicht.

Warnung
Diese Funktion hat kein spezielles Verhalten für Null-Zeichen, die in unicode eingebettet sind. Infolgedessen bleiben Strings, die Null-Zeichen enthalten, im zurückgegebenen String erhalten, was einige C-Funktionen als String-Ende interpretieren könnten, was zu einer Kürzung führt. Wenn eine Kürzung ein Problem darstellt, wird empfohlen, stattdessen PyUnicode_AsUTF8AndSize() zu verwenden.


Hinzugefügt in Version 3.3.


Geändert in Version 3.7: Der Rückgabetyp ist jetzt const char * anstelle von char *.





UTF-32 Codecs¶
Dies sind die UTF-32-Codec-APIs


PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Dekodiert size Bytes aus einem UTF-32-kodierten Pufferstring und gibt das entsprechende Unicode-Objekt zurück. errors (falls nicht NULL) definiert die Fehlerbehandlung. Standardmäßig ist dies „strict“.
Wenn byteorder nicht NULL ist, beginnt der Dekoder mit der Dekodierung in der angegebenen Byte-Reihenfolge.
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian


Wenn *byteorder null ist und die ersten vier Bytes der Eingabedaten ein Byte Order Mark (BOM) sind, schaltet der Dekoder in diese Byte-Reihenfolge um und das BOM wird nicht in den resultierenden Unicode-String kopiert. Wenn *byteorder -1 oder 1 ist, wird jedes Byte Order Mark in die Ausgabe kopiert.
Nach Abschluss wird *byteorder auf die aktuelle Byte-Reihenfolge am Ende der Eingabedaten gesetzt.
Wenn byteorder NULL ist, startet der Codec im nativen Reihenfolgemodus.
Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Wenn consumed NULL ist, verhält es sich wie PyUnicode_DecodeUTF32(). Wenn consumed nicht NULL ist, behandelt PyUnicode_DecodeUTF32Stateful() nachfolgende unvollständige UTF-32-Byte-Sequenzen (wie eine Anzahl von Bytes, die nicht durch vier teilbar ist) nicht als Fehler. Diese Bytes werden nicht dekodiert und die Anzahl der dekodierten Bytes wird in consumed gespeichert.




PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Gibt einen Python-Byte-String mit der UTF-32-Kodierung in nativer Byte-Reihenfolge zurück. Der String beginnt immer mit einem BOM-Markierungszeichen. Die Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




UTF-16 Codecs¶
Dies sind die UTF-16-Codec-APIs


PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Dekodiert size Bytes aus einem UTF-16-kodierten Pufferstring und gibt das entsprechende Unicode-Objekt zurück. errors (falls nicht NULL) definiert die Fehlerbehandlung. Standardmäßig ist dies „strict“.
Wenn byteorder nicht NULL ist, beginnt der Dekoder mit der Dekodierung in der angegebenen Byte-Reihenfolge.
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian


Wenn *byteorder null ist und die ersten zwei Bytes der Eingabedaten ein Byte Order Mark (BOM) sind, schaltet der Dekoder in diese Byte-Reihenfolge um und das BOM wird nicht in den resultierenden Unicode-String kopiert. Wenn *byteorder -1 oder 1 ist, wird jedes Byte Order Mark in die Ausgabe kopiert (wo es entweder zu einem \ufeff oder einem \ufffe-Zeichen führt).
Nach Abschluss wird *byteorder auf die aktuelle Byte-Reihenfolge am Ende der Eingabedaten gesetzt.
Wenn byteorder NULL ist, startet der Codec im nativen Reihenfolgemodus.
Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Wenn consumed NULL ist, verhält es sich wie PyUnicode_DecodeUTF16(). Wenn consumed nicht NULL ist, behandelt PyUnicode_DecodeUTF16Stateful() nachfolgende unvollständige UTF-16-Byte-Sequenzen (wie eine ungerade Anzahl von Bytes oder ein aufgeteiltes Surrogatpaar) nicht als Fehler. Diese Bytes werden nicht dekodiert und die Anzahl der dekodierten Bytes wird in consumed gespeichert.




PyObject *PyUnicode_AsUTF16String(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Gibt einen Python-Byte-String mit der UTF-16-Kodierung in nativer Byte-Reihenfolge zurück. Der String beginnt immer mit einem BOM-Markierungszeichen. Die Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




UTF-7 Codecs¶
Dies sind die UTF-7-Codec-APIs


PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des UTF-7-kodierten Strings str. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Wenn consumed NULL ist, verhält es sich wie PyUnicode_DecodeUTF7(). Wenn consumed nicht NULL ist, werden nachfolgende unvollständige UTF-7-Base64-Abschnitte nicht als Fehler behandelt. Diese Bytes werden nicht dekodiert und die Anzahl der dekodierten Bytes wird in consumed gespeichert.




Unicode-Escape Codecs¶
Dies sind die APIs des „Unicode Escape“-Codecs


PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des Unicode-Escape-kodierten Strings str. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt mit Unicode-Escape und gibt das Ergebnis als Byte-Objekt zurück. Die Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




Raw-Unicode-Escape Codecs¶
Dies sind die APIs des „Raw Unicode Escape“-Codecs


PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des Raw-Unicode-Escape-kodierten Strings str. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt mit Raw-Unicode-Escape und gibt das Ergebnis als Byte-Objekt zurück. Die Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




Latin-1 Codecs¶
Dies sind die Latin-1-Codec-APIs: Latin-1 entspricht den ersten 256 Unicode-Ordinalzahlen und nur diese werden von den Codecs beim Kodieren akzeptiert.


PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des Latin-1-kodierten Strings str. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt mit Latin-1 und gibt das Ergebnis als Python-Byte-Objekt zurück. Die Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




ASCII Codecs¶
Dies sind die ASCII-Codec-APIs. Nur 7-Bit-ASCII-Daten werden akzeptiert. Alle anderen Codes erzeugen Fehler.


PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des ASCII-kodierten Strings str. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt mit ASCII und gibt das Ergebnis als Python-Byte-Objekt zurück. Die Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn der Codec eine Ausnahme ausgelöst hat.




Character Map Codecs¶
Dieser Codec ist besonders, da er zur Implementierung vieler verschiedener Codecs verwendet werden kann (und dies tatsächlich getan wurde, um die meisten Standardcodecs zu erhalten, die im Paket encodings enthalten sind). Der Codec verwendet Abbildungen zum Kodieren und Dekodieren von Zeichen. Die bereitgestellten Abbildungsobjekte müssen die __getitem__()-Schnittstelle unterstützen; Wörterbücher und Sequenzen eignen sich gut.
Dies sind die Mapping-Codec-APIs


PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des kodierten Strings str unter Verwendung des gegebenen mapping-Objekts. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde.
Wenn mapping NULL ist, wird die Latin-1-Dekodierung angewendet. Andernfalls muss mapping Byte-Ordinalzahlen (Ganzzahlen im Bereich von 0 bis 255) auf Unicode-Strings, Ganzzahlen (die dann als Unicode-Ordinalzahlen interpretiert werden) oder None abbilden. Nicht zugeordnete Datenbytes – solche, die einen LookupError verursachen, sowie solche, die auf None, 0xFFFE oder '\ufffe' abgebildet werden – werden als undefinierte Zuordnungen behandelt und verursachen einen Fehler.




PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Kodiert ein Unicode-Objekt unter Verwendung des gegebenen mapping-Objekts und gibt das Ergebnis als Bytes-Objekt zurück. Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde.
Das mapping-Objekt muss Unicode-Ordinalzahlen auf Bytes-Objekte, Ganzzahlen im Bereich von 0 bis 255 oder None abbilden. Nicht zugeordnete Zeichen-Ordinalzahlen (solche, die einen LookupError verursachen) sowie solche, die auf None abgebildet werden, werden als „undefinierte Zuordnung“ behandelt und verursachen einen Fehler.


Die folgende Codec-API ist speziell, da sie Unicode zu Unicode abbildet.


PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Übersetzt einen String, indem eine Zeichenzuordnungstabelle darauf angewendet wird, und gibt das resultierende Unicode-Objekt zurück. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde.
Die Zuordnungstabelle muss Unicode-Ordinalzahlen auf Unicode-Ordinalzahlen oder None (was die Löschung des Zeichens verursacht) abbilden.
Zuordnungstabellen müssen nur die __getitem__()-Schnittstelle bereitstellen; Wörterbücher und Sequenzen eignen sich gut. Nicht zugeordnete Zeichen-Ordinalzahlen (solche, die einen LookupError verursachen) bleiben unberührt und werden 1:1 kopiert.
errors hat die übliche Bedeutung für Codecs. Es kann NULL sein, was die Verwendung der Standardfehlerbehandlung anzeigt.




MBCS-Codecs für Windows¶
Dies sind die MBCS-Codec-APIs. Sie sind derzeit nur unter Windows verfügbar und verwenden die Win32-MBCS-Konverter zur Implementierung der Konvertierungen. Beachten Sie, dass MBCS (oder DBCS) eine Klasse von Kodierungen ist, nicht nur eine einzige. Die Zielkodierung wird durch die Benutzereinstellungen auf dem Computer definiert, auf dem der Codec ausgeführt wird.


PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI unter Windows seit Version 3.7.Erstellt ein Unicode-Objekt durch Dekodierung von size Bytes des MBCS-kodierten Strings str. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde.




PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI unter Windows seit Version 3.7.Wenn consumed NULL ist, verhält es sich wie PyUnicode_DecodeMBCS(). Wenn consumed nicht NULL ist, dekodiert PyUnicode_DecodeMBCSStateful() keine nachfolgenden Lead-Bytes und die Anzahl der dekodierten Bytes wird in consumed gespeichert.




PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI unter Windows seit Version 3.7.Ähnlich wie PyUnicode_DecodeMBCSStateful(), verwendet jedoch die von code_page angegebene Codeseite.




PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI unter Windows seit Version 3.7.Kodiert ein Unicode-Objekt mit MBCS und gibt das Ergebnis als Python-Bytes-Objekt zurück. Fehlerbehandlung ist „strict“. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde.




PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶

Rückgabewert: Neue Referenz. Teil der Stable ABI unter Windows seit Version 3.7.Kodiert das Unicode-Objekt unter Verwendung der angegebenen Codeseite und gibt ein Python-Bytes-Objekt zurück. Gibt NULL zurück, wenn vom Codec eine Ausnahme ausgelöst wurde. Verwenden Sie die Codeseite CP_ACP, um den MBCS-Encoder zu erhalten.

Hinzugefügt in Version 3.3.






Methoden und Slot-Funktionen¶
Die folgenden APIs sind in der Lage, Unicode-Objekte und Strings als Eingabe zu verarbeiten (wir bezeichnen sie in den Beschreibungen als Strings) und geben entsprechend Unicode-Objekte oder Ganzzahlen zurück.
Sie geben alle NULL oder -1 zurück, wenn ein Fehler auftritt.


PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Verketten von zwei Strings, was zu einem neuen Unicode-String führt.




PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Teilt einen String und gibt eine Liste von Unicode-Strings zurück. Wenn sep NULL ist, wird die Teilung an allen Leerzeichen-Substrings vorgenommen. Andernfalls wird an dem angegebenen Trennzeichen geteilt. Es werden maximal maxsplit Teilungen vorgenommen. Bei negativen Werten gibt es kein Limit. Trennzeichen sind nicht in der Ergebnisliste enthalten.
Bei einem Fehler wird NULL mit einer gesetzten Ausnahme zurückgegeben.
Entspricht str.split().




PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Ähnlich wie PyUnicode_Split(), aber die Teilung erfolgt beginnend am Ende des Strings.
Bei einem Fehler wird NULL mit einer gesetzten Ausnahme zurückgegeben.
Entspricht str.rsplit().




PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Teilt einen Unicode-String an Zeilenumbrüchen und gibt eine Liste von Unicode-Strings zurück. CRLF wird als ein Zeilenumbruch betrachtet. Wenn keepends 0 ist, werden die Zeilenumbruchzeichen nicht in die resultierenden Strings aufgenommen.




PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Teilt einen Unicode-String am ersten Vorkommen von sep und gibt ein 3-Tupel zurück, das den Teil vor dem Trennzeichen, das Trennzeichen selbst und den Teil nach dem Trennzeichen enthält. Wenn das Trennzeichen nicht gefunden wird, wird ein 3-Tupel zurückgegeben, das den String selbst gefolgt von zwei leeren Strings enthält.
sep darf nicht leer sein.
Bei einem Fehler wird NULL mit einer gesetzten Ausnahme zurückgegeben.
Entspricht str.partition().




PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Ähnlich wie PyUnicode_Partition(), teilt aber einen Unicode-String am letzten Vorkommen von sep. Wenn das Trennzeichen nicht gefunden wird, wird ein 3-Tupel zurückgegeben, das zwei leere Strings gefolgt vom String selbst enthält.
sep darf nicht leer sein.
Bei einem Fehler wird NULL mit einer gesetzten Ausnahme zurückgegeben.
Entspricht str.rpartition().




PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Verbindet eine Sequenz von Strings mit dem gegebenen separator und gibt den resultierenden Unicode-String zurück.




Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶

Teil der Stable ABI.Gibt 1 zurück, wenn substr mit unicode[start:end] am angegebenen Ende übereinstimmt (direction == -1 bedeutet ein Präfix-Match, direction == 1 ein Suffix-Match), andernfalls 0. Gibt -1 zurück, wenn ein Fehler aufgetreten ist.




Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶

Teil der Stable ABI.Gibt die erste Position von substr in unicode[start:end] unter Verwendung der angegebenen direction zurück (direction == 1 bedeutet eine Vorwärtssuche, direction == -1 eine Rückwärtssuche). Der Rückgabewert ist der Index des ersten Treffers; ein Wert von -1 bedeutet, dass kein Treffer gefunden wurde, und -2 bedeutet, dass ein Fehler aufgetreten ist und eine Ausnahme gesetzt wurde.




Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)¶

Teil der Stable ABI seit Version 3.7.Gibt die erste Position des Zeichens ch in unicode[start:end] unter Verwendung der angegebenen direction zurück (direction == 1 bedeutet eine Vorwärtssuche, direction == -1 eine Rückwärtssuche). Der Rückgabewert ist der Index des ersten Treffers; ein Wert von -1 bedeutet, dass kein Treffer gefunden wurde, und -2 bedeutet, dass ein Fehler aufgetreten ist und eine Ausnahme gesetzt wurde.

Hinzugefügt in Version 3.3.


Geändert in Version 3.7: start und end werden nun so angepasst, dass sie sich wie unicode[start:end] verhalten.





Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)¶

Teil der Stable ABI.Gibt die Anzahl der nicht überlappenden Vorkommen von substr in unicode[start:end] zurück. Gibt -1 zurück, wenn ein Fehler aufgetreten ist.




PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Ersetzt maximal maxcount Vorkommen von substr in unicode durch replstr und gibt das resultierende Unicode-Objekt zurück. maxcount == -1 bedeutet, alle Vorkommen zu ersetzen.




int PyUnicode_Compare(PyObject *left, PyObject *right)¶

Teil der Stable ABI.Vergleicht zwei Strings und gibt -1, 0 oder 1 für kleiner als, gleich bzw. größer als zurück.
Diese Funktion gibt bei einem Fehler -1 zurück, daher sollte man PyErr_Occurred() aufrufen, um nach Fehlern zu suchen.

Siehe auch
Die Funktion PyUnicode_Equal().





int PyUnicode_Equal(PyObject *a, PyObject *b)¶

Teil des Stable ABI seit Version 3.14.Prüft, ob zwei Strings gleich sind.

Gibt 1 zurück, wenn a gleich b ist.
Gibt 0 zurück, wenn a nicht gleich b ist.
Setzen Sie eine TypeError Ausnahme und geben Sie -1 zurück, wenn a oder b kein str-Objekt ist.

Die Funktion ist immer erfolgreich, wenn a und b str-Objekte sind.
Die Funktion arbeitet für str-Unterklassen, beachtet jedoch keine benutzerdefinierte __eq__()-Methode.

Siehe auch
Die Funktion PyUnicode_Compare().


Hinzugefügt in Version 3.14.





int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)¶

Teil des Stable ABI seit Version 3.13.Vergleicht ein Unicode-Objekt mit einem Zeichenpuffer, der als UTF-8 oder ASCII kodiert interpretiert wird, und gibt `true` (1) zurück, wenn sie gleich sind, oder `false` (0) andernfalls. Wenn das Unicode-Objekt Surrogat-Codepunkte (U+D800 - U+DFFF) enthält oder die C-Zeichenkette kein gültiges UTF-8 ist, wird `false` (0) zurückgegeben.
Diese Funktion löst keine Ausnahmen aus.

Hinzugefügt in Version 3.13.





int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)¶

Teil des Stable ABI seit Version 3.13.Ähnlich wie PyUnicode_EqualToUTF8AndSize(), berechnet aber die Länge von string mit strlen(). Wenn das Unicode-Objekt Nullzeichen enthält, wird `false` (0) zurückgegeben.

Hinzugefügt in Version 3.13.





int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)¶

Teil der Stable ABI.Vergleicht ein Unicode-Objekt, unicode, mit string und gibt -1, 0, 1 für kleiner als, gleich und größer als zurück. Es ist am besten, nur ASCII-kodierte Zeichenketten zu übergeben, aber die Funktion interpretiert die Eingabezeichenkette als ISO-8859-1, wenn sie Nicht-ASCII-Zeichen enthält.
Diese Funktion löst keine Ausnahmen aus.




PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Vergleicht reichhaltig zwei Unicode-Zeichenketten und gibt eines der folgenden zurück

NULL im Falle einer ausgelösten Ausnahme
Py_True oder Py_False für erfolgreiche Vergleiche
Py_NotImplemented im Falle einer unbekannten Typenkombination

Mögliche Werte für op sind Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT und Py_LE.




PyObject *PyUnicode_Format(PyObject *format, PyObject *args)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Gibt ein neues Zeichenkettenobjekt aus format und args zurück; dies ist analog zu format % args.




int PyUnicode_Contains(PyObject *unicode, PyObject *substr)¶

Teil der Stable ABI.Prüft, ob substr in unicode enthalten ist, und gibt entsprechend `true` oder `false` zurück.
substr muss zu einer Unicode-Zeichenkette mit einem Element zwangfähig sein. -1 wird zurückgegeben, wenn ein Fehler aufgetreten ist.




void PyUnicode_InternInPlace(PyObject **p_unicode)¶

Teil der Stable ABI.Interniert das Argument *p_unicode an Ort und Stelle. Das Argument muss die Adresse einer Zeigervariablen sein, die auf ein Python-Unicode-Zeichenkettenobjekt zeigt. Wenn eine vorhandene internierte Zeichenkette existiert, die mit *p_unicode identisch ist, wird *p_unicode darauf gesetzt (die Referenz auf das alte Zeichenkettenobjekt wird freigegeben und eine neue starke Referenz auf das internierte Zeichenkettenobjekt erstellt), andernfalls wird *p_unicode unverändert gelassen und interniert.
(Klarstellung: Auch wenn viel über Referenzen gesprochen wird, betrachten Sie diese Funktion als referenzneutral. Sie müssen das Objekt, das Sie übergeben, besitzen; nach dem Aufruf besitzen Sie die übergebene Referenz nicht mehr, aber Sie besitzen neu das Ergebnis.)
Diese Funktion löst niemals eine Ausnahme aus. Im Fehlerfall wird das Argument unverändert gelassen, ohne es zu internieren.
Instanzen von Unterklassen von str dürfen nicht internisiert werden, d.h. PyUnicode_CheckExact(*p_unicode) muss wahr sein. Wenn dies nicht der Fall ist, wird das Argument – wie bei jedem anderen Fehler – unverändert gelassen.
Beachten Sie, dass internierte Zeichenketten nicht „unsterblich“ sind. Sie müssen eine Referenz auf das Ergebnis behalten, um von der Internierung zu profitieren.




PyObject *PyUnicode_InternFromString(const char *str)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.Eine Kombination aus PyUnicode_FromString() und PyUnicode_InternInPlace(), gedacht für statisch zugewiesene Zeichenketten.
Gibt eine neue („besitzte“) Referenz auf entweder ein neues, internierte Unicode-Zeichenkettenobjekt oder ein früheres, internierte Zeichenkettenobjekt mit demselben Wert zurück.
Python kann eine Referenz auf das Ergebnis behalten oder es unsterblich machen und so verhindern, dass es sofort vom Garbage Collector bereinigt wird. Für die Internierung einer unbegrenzten Anzahl verschiedener Zeichenketten, wie sie aus Benutzereingaben stammen, ist es vorzuziehen, stattdessen PyUnicode_FromString() und PyUnicode_InternInPlace() direkt aufzurufen.




unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)¶

Gibt einen von Null verschiedenen Wert zurück, wenn str interniert ist, Null andernfalls. Das Argument str muss eine Zeichenkette sein; dies wird nicht überprüft. Diese Funktion ist immer erfolgreich.

CPython-Implementierungsdetails: Ein von Null verschiedener Rückgabewert kann zusätzliche Informationen darüber enthalten, wie die Zeichenkette interniert ist. Die Bedeutung solcher von Null verschiedenen Werte sowie spezifische Internierungsdetails jeder einzelnen Zeichenkette können sich zwischen CPython-Versionen ändern.





PyUnicodeWriter¶
Die PyUnicodeWriter API kann verwendet werden, um ein Python str-Objekt zu erstellen.

Hinzugefügt in Version 3.14.



type PyUnicodeWriter¶

Eine Unicode-Writer-Instanz.
Die Instanz muss entweder mit PyUnicodeWriter_Finish() bei Erfolg oder mit PyUnicodeWriter_Discard() bei einem Fehler zerstört werden.




PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)¶

Erstellt eine Unicode-Writer-Instanz.
length muss größer oder gleich 0 sein.
Wenn length größer als 0 ist, wird ein interner Puffer der Größe length Zeichen vorab zugewiesen.
Setzt eine Ausnahme und gibt NULL bei einem Fehler zurück.




PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)¶

Gibt das finale Python str-Objekt zurück und zerstört die Writer-Instanz.
Setzt eine Ausnahme und gibt NULL bei einem Fehler zurück.
Die Writer-Instanz ist nach diesem Aufruf ungültig.




void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)¶

Verwirft den internen Unicode-Puffer und zerstört die Writer-Instanz.
Wenn writer NULL ist, wird keine Operation durchgeführt.
Die Writer-Instanz ist nach diesem Aufruf ungültig.




int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)¶

Schreibt das einzelne Unicode-Zeichen ch in writer.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.




int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

Dekodiert die Zeichenkette str aus UTF-8 im Strict-Modus und schreibt die Ausgabe in writer.
size ist die Länge der Zeichenkette in Bytes. Wenn size gleich -1 ist, wird strlen(str) aufgerufen, um die Zeichenkettenlänge zu ermitteln.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.
Siehe auch PyUnicodeWriter_DecodeUTF8Stateful().




int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

Schreibt die ASCII-Zeichenkette str in writer.
size ist die Länge der Zeichenkette in Bytes. Wenn size gleich -1 ist, wird strlen(str) aufgerufen, um die Zeichenkettenlänge zu ermitteln.
str darf nur ASCII-Zeichen enthalten. Das Verhalten ist undefiniert, wenn str Nicht-ASCII-Zeichen enthält.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.

Hinzugefügt in Version 3.14.





int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)¶

Schreibt die Wide-Zeichenkette str in writer.
size ist die Anzahl der Wide-Zeichen. Wenn size gleich -1 ist, wird wcslen(str) aufgerufen, um die Zeichenkettenlänge zu ermitteln.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.




int PyUnicodeWriter_WriteUCS4(PyUnicodeWriter *writer, Py_UCS4 *str, Py_ssize_t size)¶

Schreibt die UCS4-Zeichenkette str in writer.
size ist die Anzahl der UCS4-Zeichen.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.




int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)¶

Ruft PyObject_Str() für obj auf und schreibt die Ausgabe in writer.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.




int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)¶

Ruft PyObject_Repr() für obj auf und schreibt die Ausgabe in writer.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.




int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)¶

Schreibt den Teilstring str[start:end] in writer.
str muss ein Python str-Objekt sein. start muss größer oder gleich 0 und kleiner oder gleich end sein. end muss kleiner oder gleich der Länge von str sein.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.




int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)¶

Ähnlich wie PyUnicode_FromFormat(), schreibt die Ausgabe jedoch direkt in writer.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.




int PyUnicodeWriter_DecodeUTF8Stateful(PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)¶

Dekodiert die Zeichenkette str aus UTF-8 mit dem Fehlerbehandler errors und schreibt die Ausgabe in writer.
size ist die Länge der Zeichenkette in Bytes. Wenn size gleich -1 ist, wird strlen(str) aufgerufen, um die Zeichenkettenlänge zu ermitteln.
errors ist ein Name für einen Fehlerbehandler, z.B. "replace". Wenn errors NULL ist, wird der Strict-Fehlerbehandler verwendet.
Wenn consumed nicht NULL ist, wird *consumed bei Erfolg auf die Anzahl der dekodierten Bytes gesetzt. Wenn consumed NULL ist, werden unvollständige UTF-8-Byte-Sequenzen am Ende als Fehler behandelt.
Bei Erfolg wird 0 zurückgegeben. Bei einem Fehler wird eine Ausnahme gesetzt, der Writer unverändert gelassen und -1 zurückgegeben.
Siehe auch PyUnicodeWriter_WriteUTF8().




Veraltete API¶
Die folgende API ist veraltet.


type Py_UNICODE¶

Dies ist ein Typedef von wchar_t, das je nach Plattform ein 16-Bit- oder 32-Bit-Typ ist. Bitte verwenden Sie stattdessen direkt wchar_t.

Geändert in Version 3.3: In früheren Versionen war dies ein 16-Bit- oder ein 32-Bit-Typ, je nachdem, ob Sie zur Build-Zeit eine „schmale“ oder „breite“ Unicode-Version von Python ausgewählt hatten.


Veraltet seit Version 3.13, wird in Version 3.15 entfernt.





int PyUnicode_READY(PyObject *unicode)¶

Tut nichts und gibt 0 zurück. Diese API wird nur aus Kompatibilitätsgründen beibehalten, es gibt jedoch keine Pläne, sie zu entfernen.

Hinzugefügt in Version 3.3.


Veraltet seit Version 3.10: Diese API tut seit Python 3.12 nichts mehr. Zuvor musste sie für jede mit der alten API (PyUnicode_FromUnicode() oder ähnlich) erstellte Zeichenkette aufgerufen werden.





unsigned int PyUnicode_IS_READY(PyObject *unicode)¶

Tut nichts und gibt 1 zurück. Diese API wird nur aus Kompatibilitätsgründen beibehalten, es gibt jedoch keine Pläne, sie zu entfernen.

Hinzugefügt in Version 3.3.


Veraltet seit Version 3.14: Diese API tut seit Python 3.12 nichts mehr. Zuvor konnte sie aufgerufen werden, um zu prüfen, ob PyUnicode_READY() notwendig ist.

Modifikator	Typen
`l`	long oder unsigned long
`ll`	long long oder unsigned long long
`j`	`intmax_t` oder `uintmax_t`
`z`	`size_t` oder `ssize_t`
`t`	`ptrdiff_t`

Konvertierungsspezifizierer	Typ	Kommentar
`%`	n/a	Das literale Zeichen `%`.
`d`, `i`	Angegeben durch den Längenmodifikator	Die Dezimaldarstellung einer vorzeichenbehafteten C-Ganzzahl.
`u`	Angegeben durch den Längenmodifikator	Die Dezimaldarstellung einer vorzeichenlosen C-Ganzzahl.
`o`	Angegeben durch den Längenmodifikator	Die Oktaldarstellung einer vorzeichenlosen C-Ganzzahl.
`x`	Angegeben durch den Längenmodifikator	Die Hexadezimaldarstellung einer vorzeichenlosen C-Ganzzahl (Kleinbuchstaben).
`X`	Angegeben durch den Längenmodifikator	Die Hexadezimaldarstellung einer vorzeichenlosen C-Ganzzahl (Großbuchstaben).
`c`	int	Ein einzelnes Zeichen.
`s`	const char* oder const wchar_t*	Ein nullterminiertes C-Zeichenarray.
`p`	const void*	Die Hex-Darstellung eines C-Zeigers. Weitgehend äquivalent zu `printf("%p")`, außer dass garantiert wird, dass es mit dem Literal `0x` beginnt, unabhängig davon, was die `printf` des Systems liefert.
`A`	PyObject*	Das Ergebnis des Aufrufs von `ascii()`.
`U`	PyObject*	Ein Unicode-Objekt.
`V`	PyObject, const char oder const wchar_t*	Ein Unicode-Objekt (das `NULL` sein kann) und ein nullterminiertes C-Zeichenarray als zweiter Parameter (das verwendet wird, wenn der erste Parameter `NULL` ist).
`S`	PyObject*	Das Ergebnis des Aufrufs von `PyObject_Str()`.
`R`	PyObject*	Das Ergebnis des Aufrufs von `PyObject_Repr()`.
`T`	PyObject*	Ruft den vollständig qualifizierten Namen eines Objekttyps ab; ruft `PyType_GetFullyQualifiedName()` auf.
`#T`	PyObject*	Ähnlich dem `T`-Format, verwendet jedoch einen Doppelpunkt (`:`) als Trennzeichen zwischen dem Modulnamen und dem qualifizierten Namen.
`N`	PyTypeObject*	Ruft den vollständig qualifizierten Namen eines Typs ab; ruft `PyType_GetFullyQualifiedName()` auf.
`#N`	PyTypeObject*	Ähnlich dem `N`-Format, verwendet jedoch einen Doppelpunkt (`:`) als Trennzeichen zwischen dem Modulnamen und dem qualifizierten Namen.

Unicode-Objekte und Codecs¶

Unicode-Objekte¶

Unicode-Typ¶

Unicode-Zeicheneigenschaften¶

Erstellen und Zugreifen auf Unicode-Zeichenketten¶

Locale-Kodierung¶

Dateisystem-Kodierung¶

wchar_t-Unterstützung¶

Integrierte Codecs¶

Generische Codecs¶

UTF-8-Codecs¶

UTF-32 Codecs¶

UTF-16 Codecs¶

UTF-7 Codecs¶

Unicode-Escape Codecs¶

Raw-Unicode-Escape Codecs¶

Latin-1 Codecs¶

ASCII Codecs¶

Character Map Codecs¶

MBCS-Codecs für Windows¶

Methoden und Slot-Funktionen¶

PyUnicodeWriter¶

Veraltete API¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

Flag	Bedeutung
`0`	Der Wert wird für numerische Werte mit Nullen aufgefüllt.
`-`	Der konvertierte Wert ist linksbündig ausgerichtet (überschreibt das `0`-Flag, wenn beide angegeben sind).