Unicode-objekt och codecs

Unicode-objekt

Sedan implementeringen av PEP 393 i Python 3.3 använder Unicode-objekt internt en mängd olika representationer, för att möjliggöra hantering av hela utbudet av Unicode-tecken samtidigt som de är minneseffektiva. Det finns specialfall för strängar där alla kodpunkter är under 128, 256 eller 65536; annars måste kodpunkterna vara under 1114112 (vilket är hela Unicode-intervallet).

UTF-8-representationen skapas på begäran och cachelagras i Unicode-objektet.

Anteckning

Representationen Py_UNICODE har tagits bort sedan Python 3.12 med föråldrade API:er. Se PEP 623 för mer information.

Unicode-typ

Dessa är de grundläggande Unicode-objekttyperna som används för Unicode-implementeringen i Python:

PyTypeObject PyUnicode_Type
En del av Stabil ABI.

Denna instans av PyTypeObject representerar Pythons Unicode-typ. Den är exponerad för Python-kod som str.

PyTypeObject PyUnicodeIter_Type
En del av Stabil ABI.

Denna instans av PyTypeObject representerar Pythons Unicode iterator-typ. Den används för att iterera över Unicode-strängobjekt.

type Py_UCS4
type Py_UCS2
type Py_UCS1
En del av Stabil ABI.

Dessa typer är typdefinitioner för osignerade heltalstyper som är tillräckligt breda för att innehålla tecken på 32 bitar, 16 bitar respektive 8 bitar. När du hanterar enstaka Unicode-tecken, använd Py_UCS4.

Tillagd i version 3.3.

type PyASCIIObject
type PyCompactUnicodeObject
type PyUnicodeObject

Dessa subtyper av PyObject representerar ett Python Unicode-objekt. I nästan alla fall bör de inte användas direkt, eftersom alla API-funktioner som hanterar Unicode-objekt tar och returnerar PyObject-pekare.

Tillagd i version 3.3.

Följande API:er är C-makron och statiska inline-funktioner för snabba kontroller och åtkomst till interna skrivskyddade data i Unicode-objekt:

int PyUnicode_Check(PyObject *obj)

Returnerar true om objektet obj är ett Unicode-objekt eller en instans av en Unicode-subtyp. Denna funktion lyckas alltid.

int PyUnicode_CheckExact(PyObject *obj)

Returnerar true om objektet obj är ett Unicode-objekt, men inte en instans av en subtyp. Denna funktion lyckas alltid.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)

Returnerar längden på Unicode-strängen i kodpunkter. unicode måste vara ett Unicode-objekt i den ”kanoniska” representationen (kontrolleras inte).

Tillagd i version 3.3.

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)
Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)

Returnerar en pekare till den kanoniska representationen omgjord till heltalstyperna UCS1, UCS2 eller UCS4 för direkt teckenåtkomst. Inga kontroller utförs om den kanoniska representationen har rätt teckenstorlek; använd PyUnicode_KIND() för att välja rätt funktion.

Tillagd i version 3.3.

PyUnicode_1BYTE_KIND
PyUnicode_2BYTE_KIND
PyUnicode_4BYTE_KIND

Returvärden för makrot PyUnicode_KIND().

Tillagd i version 3.3.

Ändrad i version 3.12: PyUnicode_WCHAR_KIND har tagits bort.

int PyUnicode_KIND(PyObject *unicode)

Returnerar en av PyUnicodes kindkonstanter (se ovan) som anger hur många byte per tecken som detta Unicode-objekt använder för att lagra sina data. unicode måste vara ett Unicode-objekt i den ”kanoniska” representationen (ej kontrollerat).

Tillagd i version 3.3.

void *PyUnicode_DATA(PyObject *unicode)

Returnerar en voidpekare till den råa Unicode-bufferten. unicode måste vara ett Unicode-objekt i den ”kanoniska” representationen (kontrolleras inte).

Tillagd i version 3.3.

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

Skriv kodpunktens värde till det givna nollbaserade indexet i en sträng.

Värdet kind och pekaren data måste ha erhållits från en sträng med hjälp av PyUnicode_KIND() respektive PyUnicode_DATA(). Du måste hålla en referens till den strängen när du anropar PyUnicode_WRITE(). Alla krav för PyUnicode_WriteChar() gäller också.

Funktionen utför inga kontroller för något av sina krav och är avsedd att användas i loopar.

Tillagd i version 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

Läser en kodpunkt från en kanonisk representation data (som erhålls med PyUnicode_DATA()). Inga kontroller eller ready-anrop utförs.

Tillagd i version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)

Läser ett tecken från ett Unicode-objekt unicode, som måste vara i den ”kanoniska” representationen. Detta är mindre effektivt än PyUnicode_READ() om du gör flera på varandra följande läsningar.

Tillagd i version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)

Returnerar den maximala kodpunkt som är lämplig för att skapa en annan sträng baserad på unicode, som måste vara i den ”kanoniska” representationen. Detta är alltid en approximation men mer effektivt än att iterera över strängen.

Tillagd i version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)
En del av Stabil ABI.

Returnerar 1 om strängen är en giltig identifierare enligt språkdefinitionen, avsnitt Namn (identifierare och nyckelord). Returnerar 0 annars.

Ändrad i version 3.9: Funktionen anropar inte Py_FatalError() längre om strängen inte är klar.

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)

Returnerar true om strängen bara innehåller ASCII-tecken. Motsvarar str.isascii().

Tillagd i version 3.2.

Egenskaper för Unicode-tecken

Unicode tillhandahåller många olika teckenegenskaper. De som oftast behövs är tillgängliga via dessa makron som mappas till C-funktioner beroende på Python-konfigurationen.

int Py_UNICODE_ISSPACE(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett blankstegstecken.

int Py_UNICODE_ISLOWER(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett gemener-tecken.

int Py_UNICODE_ISUPPER(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett versalt tecken.

int Py_UNICODE_ISTITLE(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är en titelbokstav.

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett tecken för radbrytning.

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett decimaltecken.

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett siffertecken.

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett numeriskt tecken.

int Py_UNICODE_ISALPHA(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett alfabetiskt tecken.

int Py_UNICODE_ISALNUM(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett alfanumeriskt tecken.

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)

Returnerar 1 eller 0 beroende på om ch är ett tryckbart tecken, i betydelsen str.isprintable().

Dessa API:er kan användas för snabba direkta teckenkonverteringar:

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)

Returnera tecknet ch konverterat till gemener.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

Returnera tecknet ch konverterat till versaler.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

Returnera tecknet ch konverterat till titelfall.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)

Returnerar tecknet ch konverterat till ett positivt decimalt heltal. Returnera -1 om detta inte är möjligt. Denna funktion ger inte upphov till undantag.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)

Returnerar tecknet ch omvandlat till ett ensiffrigt heltal. Returnera -1 om detta inte är möjligt. Denna funktion ger inte upphov till undantag.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)

Returnerar tecknet ch omvandlat till en dubbel. Returnera -1.0 om detta inte är möjligt. Denna funktion ger inte upphov till undantag.

Dessa API:er kan användas för att arbeta med surrogat:

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

Kontrollera om ch är ett surrogat (0xD800 <= ch <= 0xDFFF).

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)

Kontrollera om ch är ett högt surrogat (0xD800 <= ch <= 0xDBFF).

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)

Kontrollera om ch är ett lågt surrogat (0xDC00 <= ch <= 0xDFFF).

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)

Sammanfogar två surrogatkodpunkter och returnerar ett enda Py_UCS4-värde. high och low är det inledande respektive det avslutande surrogatet i ett surrogatpar. high måste ligga inom intervallet [0xD800; 0xDBFF] och low måste ligga inom intervallet [0xDC00; 0xDFFF].

Skapa och få tillgång till Unicode-strängar

Använd dessa API:er för att skapa Unicode-objekt och få tillgång till deras grundläggande sekvensegenskaper:

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
Returnera värde: Ny referens.

Skapa ett nytt Unicode-objekt. maxchar bör vara den verkliga maximala kodpunkten som ska placeras i strängen. Som en approximation kan det avrundas uppåt till närmaste värde i sekvensen 127, 255, 65535, 1114111.

Vid fel, sätt ett undantag och returnera NULL.

Efter skapandet kan strängen fyllas med PyUnicode_WriteChar(), PyUnicode_CopyCharacters(), PyUnicode_Fill(), PyUnicode_WRITE() eller liknande. Eftersom strängar är tänkta att vara oföränderliga, se till att inte ”använda” resultatet medan det modifieras. I synnerhet innan den fylls med sitt slutliga innehåll, en sträng:

  • får inte vara hashad,

  • får inte vara konverterad till UTF-8, eller någon annan icke-”kanonisk” representation,

  • får inte få sitt referensantal ändrat,

  • får inte delas med kod som kan göra något av ovanstående.

Denna lista är inte uttömmande. Att undvika dessa användningsområden är ditt ansvar; Python kontrollerar inte alltid dessa krav.

För att undvika att oavsiktligt exponera ett delvis skrivet strängobjekt, använd hellre API:et PyUnicodeWriter eller någon av funktionerna PyUnicode_From* nedan.

Tillagd i version 3.3.

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)
Returnera värde: Ny referens.

Skapa ett nytt Unicode-objekt med den angivna typen (möjliga värden är PyUnicode_1BYTE_KIND etc., som returneras av PyUnicode_KIND()). Buffer måste peka på en array av size-enheter på 1, 2 eller 4 byte per tecken, enligt vad som anges av kind.

Om det behövs kopieras och transformeras indata buffer till den kanoniska representationen. Om bufferten till exempel är en UCS4-sträng (PyUnicode_4BYTE_KIND) och den endast består av kodpunkter i UCS1-intervallet, kommer den att omvandlas till UCS1 (PyUnicode_1BYTE_KIND).

Tillagd i version 3.3.

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt från char-bufferten str. Bytesen kommer att tolkas som UTF-8-kodade. Bufferten kopieras in i det nya objektet. Returvärdet kan vara ett delat objekt, d.v.s. det är inte tillåtet att ändra data.

Denna funktion ger upphov till SystemError när:

  • storlek < 0,

  • str är NULL och size > 0

Ändrad i version 3.12: str == NULL med size > 0 är inte tillåtet längre.

PyObject *PyUnicode_FromString(const char *str)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt från en UTF-8-kodad nollavslutad char-buffert str.

PyObject *PyUnicode_FromFormat(const char *format, ...)
Returnera värde: Ny referens. En del av Stabil ABI.

Tar en C printf()-stil format-sträng och ett variabelt antal argument, beräknar storleken på den resulterande Python Unicode-strängen och returnerar en sträng med de värden som formaterats i den. De variabla argumenten måste vara C-typer och måste exakt motsvara formattecknen i den ASCII-kodade strängen format.

En konverteringsspecifikator innehåller två eller flera tecken och har följande komponenter, som måste förekomma i denna ordning:

  1. Tecknet '%', som markerar början på specifikationen.

  2. Konverteringsflaggor (valfritt), som påverkar resultatet av vissa konverteringstyper.

  3. Minsta fältbredd (valfritt). Om den anges som en '*' (asterisk) ges den faktiska bredden i nästa argument, som måste vara av typen int, och objektet som ska konverteras kommer efter den minsta fältbredden och den valfria precisionen.

  4. Precision (valfri), anges som en '.' (punkt) följt av precisionen. Om den anges som '*' (en asterisk) anges den faktiska precisionen i nästa argument, som måste vara av typen int, och värdet som ska konverteras kommer efter precisionen.

  5. Längdmodifierare (valfritt).

  6. Typ av konvertering.

Konverteringens flaggtecken är:

Flagga

Betydelse

0

Omvandlingen kommer att nollställas för numeriska värden.

-

Det konverterade värdet lämnas justerat (åsidosätter flaggan 0 om båda är angivna).

Längdmodifierarna för följande heltalskonverteringar (d, i, o, u, x eller X) anger typen av argument (int som standard):

Modifierare

Typer

l

long eller unsigned long

ll

long long eller unsigned long long

j

intmax_t eller uintmax_t

z

size_t eller ssize_t

t

ptrdiff_t

Längdmodifieraren l för följande konverteringar s eller V anger att argumentets typ är const wchar_t*.

Konverteringsspecifikationerna är:

Specifikator för konvertering

Typ

Kommentar

%

n/a

Det bokstavliga tecknet %.

d, i

Specificeras av längdmodifieraren

Decimal representation av ett signerat C heltal.

u

Specificeras av längdmodifieraren

Decimal representation av ett osignerat C heltal.

o

Specificeras av längdmodifieraren

Oktalrepresentation av ett osignerat C- heltal.

x

Specificeras av längdmodifieraren

Den hexadecimala representationen av ett osignerat C heltal (små bokstäver).

X

Specificeras av längdmodifieraren

Den hexadecimala representationen av ett osignerat C heltal (versaler).

c

int

Ett enda tecken.

s

const char* eller const wchar_t*

En nollavslutad C-teckenmatris.

p

const void*

Hex-representationen av en C-pekare. I stort sett likvärdig med printf("%p") förutom att den garanterat börjar med den bokstavliga 0x oavsett vad plattformens printf ger.

A

PyObject*

Resultatet av att anropa ascii().

U

PyObject*

Ett Unicode-objekt.

V

PyObject*, const char* eller const wchar_t*

Ett Unicode-objekt (som kan vara NULL) och en nollterminerad C-teckenarray som andra parameter (som kommer att användas om den första parametern är NULL).

S

PyObject*

Resultatet av anropet av PyObject_Str().

R

PyObject*

Resultatet av anropet PyObject_Repr().

T

PyObject*

Hämta det fullständigt kvalificerade namnet på en objekttyp; anropa PyType_GetFullyQualifiedName().

#T

PyObject*

Liknar formatet T, men använder ett kolon (:) som avgränsare mellan modulnamnet och det kvalificerade namnet.

N

PyTypeObject*

Hämta det fullständigt kvalificerade namnet på en typ; anropa PyType_GetFullyQualifiedName().

#N

PyTypeObject*

Liknar formatet N, men använder ett kolon (:) som avgränsare mellan modulnamnet och det kvalificerade namnet.

Anteckning

Formateringsenheten för bredd är antal tecken i stället för bytes. Formateringsenheten för precision är antal byte eller wchar_t-objekt (om längdmodifieraren l används) för "%s" och "%V" (om argumentet PyObject* är NULL), och ett antal tecken för "%A", "%U", "%S", "%R" och "%V" (om argumentet PyObject* inte är NULL).

Anteckning

Till skillnad från C printf() har flaggan 0 effekt även när en precision anges för heltalskonverteringar (d, i, u, o, x eller X).

Ändrad i version 3.2: Stöd för "%lld" och "%llu" tillagt.

Ändrad i version 3.3: Stöd för "%li", "%lli" och "%zi" tillagt.

Ändrad i version 3.4: Stöd för bredd- och precisionsformatering för "%s", "%A", "%U", "%V", "%S", "%R" tillagt.

Ändrad i version 3.12: Stöd för konverteringsspecifikatorerna o och X. Stöd för längdmodifierarna j och t. Längdmodifierare tillämpas nu på alla heltalskonverteringar. Längdmodifieraren l tillämpas nu på konverteringsspecifikatorerna s och V. Stöd för variabel bredd och precision *. Stöd för flaggan -.

Ett formattecken som inte känns igen ger nu upphov till ett SystemError. I tidigare versioner ledde det till att resten av formatsträngen kopierades som den var till resultatsträngen och att eventuella extra argument ignorerades.

Ändrad i version 3.13: Stöd för formaten %T, %#T, %N och %#N har lagts till.

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)
Returnera värde: Ny referens. En del av Stabil ABI.

Identisk med PyUnicode_FromFormat() förutom att den tar exakt två argument.

PyObject *PyUnicode_FromObject(PyObject *obj)
Returnera värde: Ny referens. En del av Stabil ABI.

Kopiera en instans av en Unicode-subtyp till ett nytt äkta Unicode-objekt om det behövs. Om obj redan är ett äkta Unicode-objekt (inte en subtyp), returneras en ny strong reference till objektet.

Andra objekt än Unicode eller dess subtyper kommer att orsaka ett TypeError.

PyObject *PyUnicode_FromOrdinal(int ordinal)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt från den angivna Unicode-kodpunkten ordinal.

Ordinalen måste ligga inom range(0x110000). Om så inte är fallet uppstår ett ValueError.

PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Avkodar ett kodat objekt obj till ett Unicode-objekt.

bytes, bytearray och andra bytesliknande objekt avkodas enligt den givna kodningen och med den felhantering som definieras av errors. Båda kan vara NULL för att gränssnittet ska använda standardvärdena (se Inbyggda codecs för detaljer).

Alla andra objekt, inklusive Unicode-objekt, orsakar att en TypeError sätts.

API:et returnerar NULL om det uppstod ett fel. Den som anropar är ansvarig för att decref’a de returnerade objekten.

void PyUnicode_Append(PyObject **p_left, PyObject *right)
En del av Stabil ABI.

Lägger till strängen right i slutet av p_left. p_left måste peka på en strong reference till ett Unicode-objekt; PyUnicode_Append() frigör (”stjäl”) denna referens.

Vid fel, sätt *p_left till NULL och sätt ett undantag.

Vid framgång, sätt *p_left till en ny stark referens till resultatet.

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)
En del av Stabil ABI.

Funktionen liknar PyUnicode_Append(), med den enda skillnaden att den minskar referensantalet för right med ett.

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)
Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar en mappning som är lämplig för avkodning av en anpassad single-byte-kodning. Givet en Unicode-sträng sträng med upp till 256 tecken som representerar en kodningstabell, returnerar antingen ett kompakt internt mappningsobjekt eller en ordbok som mappar teckenordinaler till bytevärden. Utlöser ett TypeError och returnerar NULL vid ogiltig indata.

Tillagd i version 3.2.

const char *PyUnicode_GetDefaultEncoding(void)
En del av Stabil ABI.

Returnerar namnet på standardkodningen för strängar, "utf-8". Se sys.getdefaultencoding().

Den returnerade strängen behöver inte frigöras och är giltig tills tolken stängs av.

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)
En del av Stabil ABI sedan version 3.7.

Returnerar längden på Unicode-objektet i kodpunkter.

Vid fel, sätt ett undantag och returnera -1.

Tillagd i 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)

Kopierar tecken från ett Unicode-objekt till ett annat. Denna funktion utför teckenkonvertering när det är nödvändigt och faller tillbaka till memcpy() om möjligt. Returnerar -1 och sätter ett undantag vid fel, annars returneras antalet kopierade tecken.

Strängen får inte ha ”använts” ännu. Se PyUnicode_New() för detaljer.

Tillagd i version 3.3.

int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);
En del av Stabil ABI.

Ändra storlek på ett Unicode-objekt *unicode till den nya längden i kodpunkter.

Försök att ändra storlek på strängen på plats (vilket vanligtvis är snabbare än att allokera en ny sträng och kopiera tecken), eller skapa en ny sträng.

*unicode modifieras så att det pekar på det nya (storleksändrade) objektet och 0 returneras vid framgång. Annars returneras -1 och ett undantag sätts, och *unicode lämnas orörd.

Funktionen kontrollerar inte stränginnehållet, så resultatet kanske inte är en sträng i kanonisk representation.

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

Fyll en sträng med ett tecken: skriv fill_char till unicode[start:start+length].

Misslyckas om fill_char är större än strängens maximala tecken, eller om strängen har mer än 1 referens.

Strängen får inte ha ”använts” ännu. Se PyUnicode_New() för detaljer.

Returnera antalet skrivna tecken, eller returnera -1 och skapa ett undantag vid fel.

Tillagd i version 3.3.

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
En del av Stabil ABI sedan version 3.7.

Skriv ett tecken till strängen unicode vid det nollbaserade indexet. Returnerar 0 vid framgång, -1 vid fel med en undantagsuppsättning.

Denna funktion kontrollerar att unicode är ett Unicode-objekt, att indexet inte är utanför gränserna och att objektets referensantal är ett). Se PyUnicode_WRITE() för en version som hoppar över dessa kontroller, vilket gör dem till ditt ansvar.

Strängen får inte ha ”använts” ännu. Se PyUnicode_New() för detaljer.

Tillagd i version 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)
En del av Stabil ABI sedan version 3.7.

Läser ett tecken från en sträng. Denna funktion kontrollerar att unicode är ett Unicode-objekt och att index inte är utanför gränserna, till skillnad från PyUnicode_READ_CHAR(), som inte utför någon felkontroll.

Returnerar tecken vid framgång, -1 vid fel med en undantagsuppsättning.

Tillagd i version 3.3.

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)
Returnera värde: Ny referens. En del av Stabil ABI sedan version 3.7.

Returnerar en delsträng av unicode, från teckenindex start (inkluderat) till teckenindex end (exkluderat). Negativa index stöds inte. Vid fel, sätt ett undantag och returnera NULL.

Tillagd i version 3.3.

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
En del av Stabil ABI sedan version 3.7.

Kopierar strängen unicode till en UCS4-buffert, inklusive ett null-tecken, om copy_null är inställt. Returnerar NULL och anger ett undantag vid fel (i synnerhet ett SystemError om buflen är mindre än längden på unicode). buffer returneras vid framgång.

Tillagd i version 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)
En del av Stabil ABI sedan version 3.7.

Kopierar strängen unicode till en ny UCS4-buffert som allokeras med PyMem_Malloc(). Om detta misslyckas returneras NULL med MemoryError inställt. Den returnerade bufferten har alltid en extra null-kodpunkt tillagd.

Tillagd i version 3.3.

Kodning av lokala språk

Den aktuella locale-kodningen kan användas för att avkoda text från operativsystemet.

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI sedan version 3.7.

Avkodar en sträng från UTF-8 på Android och VxWorks, eller från den aktuella lokala kodningen på andra plattformar. De felhanterare som stöds är "strict" och "surrogateescape" (PEP 383). Avkodaren använder felhanteraren "strict" om errors är NULL. str måste sluta med ett nolltecken men kan inte innehålla inbäddade nolltecken.

Använd PyUnicode_DecodeFSDefaultAndSize() för att avkoda en sträng från filesystem encoding and error handler.

Denna funktion ignorerar Python UTF-8 Mode.

Se även

Funktionen Py_DecodeLocale().

Tillagd i version 3.3.

Ändrad i version 3.7: Funktionen använder nu även den aktuella lokalkodningen för felhanteraren surrogateescape, utom på Android. Tidigare användes Py_DecodeLocale() för surrogateescape, och den aktuella lokalkodningen användes för strict.

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI sedan version 3.7.

Liknar PyUnicode_DecodeLocaleAndSize(), men beräknar stränglängden med hjälp av strlen().

Tillagd i version 3.3.

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI sedan version 3.7.

Kodar ett Unicode-objekt till UTF-8 på Android och VxWorks, eller till den aktuella lokala kodningen på andra plattformar. De felhanterare som stöds är "strict" och "surrogateescape" (PEP 383). Kodaren använder felhanteraren "strict" om errors är NULL. Returnerar ett bytes-objekt. unicode kan inte innehålla inbäddade null-tecken.

Använd PyUnicode_EncodeFSDefault() för att koda en sträng till filesystem encoding and error handler.

Denna funktion ignorerar Python UTF-8 Mode.

Se även

Funktionen Py_EncodeLocale().

Tillagd i version 3.3.

Ändrad i version 3.7: Funktionen använder nu även den aktuella lokalkodningen för felhanteraren surrogateescape, utom på Android. Tidigare användes Py_EncodeLocale() för surrogateescape, och den aktuella lokalkodningen användes för strict.

Kodning av filsystem

Funktioner för kodning till och avkodning från filesystem encoding and error handler (PEP 383 och PEP 529).

För att koda filnamn till bytes under argumentparsning, bör "O&"-omvandlaren användas, med PyUnicode_FSConverter() som omvandlingsfunktion:

int PyUnicode_FSConverter(PyObject *obj, void *result)
En del av Stabil ABI.

PyArg_Parse* converter: koda str-objekt – erhållna direkt eller genom os.PathLike-gränssnittet – till bytes med PyUnicode_EncodeFSDefault(); bytes-objekt matas ut som de är. result måste vara en adress till en C-variabel av typen PyObject* (eller PyBytesObject*). Vid framgång, sätt variabeln till en ny strong reference till ett bytesobjekt som måste släppas när det inte längre används och returnera ett värde som inte är noll (Py_CLEANUP_SUPPORTED). Inbäddade nollbytes är inte tillåtna i resultatet. Vid misslyckande returneras 0 med en undantagsuppsättning.

Om obj är NULL frigör funktionen en stark referens som lagrats i den variabel som refereras av result och returnerar 1.

Tillagd i version 3.1.

Ändrad i version 3.6: Accepterar en path-like object.

För att avkoda filnamn till str under argumentparsning, bör "O&"-omvandlaren användas, med PyUnicode_FSDecoder() som omvandlingsfunktion:

int PyUnicode_FSDecoder(PyObject *obj, void *result)
En del av Stabil ABI.

PyArg_Parse* converter: avkodar bytes-objekt – erhållna antingen direkt eller indirekt genom os.PathLike-gränssnittet – till str med PyUnicode_DecodeFSDefaultAndSize(); str-objekt matas ut som de är. result måste vara en adress till en C-variabel av typen PyObject* (eller PyUnicodeObject*). Vid framgång, sätt variabeln till en ny strong reference till en Unicode object som måste släppas när den inte längre används och returnera ett icke-noll värde (Py_CLEANUP_SUPPORTED). Inbäddade nolltecken är inte tillåtna i resultatet. Vid misslyckande returneras 0 med en undantagsuppsättning.

Om obj är NULL, släpp den starka referensen till det objekt som result hänvisar till och returnera 1.

Tillagd i version 3.2.

Ändrad i version 3.6: Accepterar en path-like object.

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)
Returnera värde: Ny referens. En del av Stabil ABI.

Avkodar en sträng från filesystem encoding and error handler.

Om du behöver avkoda en sträng från den aktuella lokala kodningen, använd PyUnicode_DecodeLocaleAndSize().

Se även

Funktionen Py_DecodeLocale().

Ändrad i version 3.6: Nu används filsystemsfelhanterare.

PyObject *PyUnicode_DecodeFSDefault(const char *str)
Returnera värde: Ny referens. En del av Stabil ABI.

Avkoda en nollavslutad sträng från filesystem encoding and error handler.

Om stränglängden är känd, använd PyUnicode_DecodeFSDefaultAndSize().

Ändrad i version 3.6: Nu används filsystemsfelhanterare.

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt till filesystem encoding and error handler och returnerar bytes. Observera att det resulterande bytes-objektet kan innehålla nollbytes.

Om du behöver koda en sträng till den aktuella locale-kodningen, använd PyUnicode_EncodeLocale().

Se även

Funktionen Py_EncodeLocale().

Tillagd i version 3.2.

Ändrad i version 3.6: Nu används filsystemsfelhanterare.

Stöd för wchar_t

wchar_t-stöd för plattformar som stödjer det:

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapar ett Unicode-objekt från wchar_t-bufferten wstr med den angivna storleken. Om du anger -1 som storlek indikerar det att funktionen själv måste beräkna längden med hjälp av wcslen(). Returnerar NULL om den misslyckas.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)
En del av Stabil ABI.

Kopiera Unicode-objektets innehåll till wchar_t-bufferten wstr. Högst storlek wchar_t-tecken kopieras (exklusive ett eventuellt avslutande null-tecken). Returnerar antalet wchar_t-tecken som kopierats eller -1 i händelse av ett fel.

När wstr är NULL, returneras istället den storlek som skulle krävas för att lagra hela unicode inklusive en avslutande null.

Observera att den resulterande wchar_t*-strängen kan vara eller inte vara nollterminerad. Det är anroparens ansvar att se till att wchar_t*-strängen är nollterminerad om detta krävs av programmet. Observera också att strängen wchar_t* kan innehålla nolltecken, vilket gör att strängen blir avkortad när den används med de flesta C-funktioner.

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)
En del av Stabil ABI sedan version 3.7.

Konverterar Unicode-objektet till en bred teckensträng. Utdatasträngen slutar alltid med ett null-tecken. Om size inte är NULL, skriv antalet breda tecken (exklusive det avslutande nulltecknet) till *size. Observera att den resulterande wchar_t-strängen kan innehålla nolltecken, vilket gör att strängen blir avkortad när den används med de flesta C-funktioner. Om size är NULL och strängen wchar_t* innehåller nolltecken, uppstår ett ValueError.

Returnerar en buffert som allokerats av PyMem_New (använd PyMem_Free() för att frigöra den) vid framgång. Vid fel returneras NULL och *size är odefinierad. Skapar ett MemoryError om minnesallokeringen misslyckades.

Tillagd i version 3.2.

Ändrad i version 3.7: Utlöser ett ValueError om size är NULL och strängen wchar_t* innehåller null-tecken.

Inbyggda codecs

Python tillhandahåller en uppsättning inbyggda codecs som är skrivna i C för snabbhetens skull. Alla dessa codecs är direkt användbara via följande funktioner.

Många av följande API:er tar två argument, encoding och errors, och de har samma semantik som den inbyggda str()-konstruktören för strängobjekt.

Om encoding sätts till NULL används standardkodningen UTF-8. Filsystemets anrop bör använda PyUnicode_FSConverter() för kodning av filnamn. Detta använder filesystem encoding and error handler internt.

Felhantering anges av errors som också kan anges till NULL vilket innebär att standardhanteringen som definierats för codec används. Standardfelhanteringen för alla inbyggda codecs är ”strict” (ValueError aktiveras).

Codecs använder alla ett liknande gränssnitt. För enkelhetens skull dokumenteras endast avvikelser från följande generiska gränssnitt.

Generiska codecs

Följande makro tillhandahålls:

Py_UNICODE_REPLACEMENT_CHARACTER

Unicode-kodpunkten U+FFFD (ersättningstecken).

Detta Unicode-tecken används som ersättningstecken vid avkodning om errors-argumentet är inställt på ”replace”.

Dessa är de generiska codec-API:erna:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den kodade strängen str. encoding och errors har samma betydelse som parametrarna med samma namn i den inbyggda funktionen str(). Den codec som ska användas söks upp med hjälp av Pythons codec-register. Returnera NULL om ett undantag uppstod av codec.

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt och returnerar resultatet som ett Python bytes-objekt. encoding och errors har samma betydelse som parametrarna med samma namn i Unicode encode()-metoden. Den codec som ska användas söks upp med hjälp av Pythons codec-register. Returnera NULL om ett undantag uppstod av codec.

UTF-8-codecs

Dessa är UTF-8 codec API:er:

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den UTF-8-kodade strängen str. Returnerar NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Returnera värde: Ny referens. En del av Stabil ABI.

Om consumed är NULL, uppför sig som PyUnicode_DecodeUTF8(). Om consumed inte är NULL, kommer efterföljande ofullständiga UTF-8 byte-sekvenser inte att behandlas som ett fel. Dessa byte kommer inte att avkodas och antalet byte som har avkodats kommer att lagras i consumed.

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt med UTF-8 och returnerar resultatet som Python bytes-objekt. Felhanteringen är ”strikt”. Returnera NULL om ett undantag uppstod av codec.

Funktionen misslyckas om strängen innehåller surrogatkodpunkter (U+D800 - U+DFFF).

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
En del av Stabil ABI sedan version 3.10.

Returnerar en pekare till UTF-8-kodningen av Unicode-objektet och lagrar storleken på den kodade representationen (i byte) i size. Argumentet size kan vara NULL; i så fall lagras ingen storlek. Den returnerade bufferten har alltid en extra null-byte tillagd (ingår inte i size), oavsett om det finns några andra null-kodpunkter.

Vid fel, sätt ett undantag, sätt size till -1 (om det inte är NULL) och returnera NULL.

Funktionen misslyckas om strängen innehåller surrogatkodpunkter (U+D800 - U+DFFF).

Detta cachelagrar UTF-8-representationen av strängen i Unicode-objektet, och efterföljande anrop returnerar en pekare till samma buffert. Den som anropar är inte ansvarig för att deallokera bufferten. Bufferten deallokeras och pekare till den blir ogiltiga när Unicode-objektet garbage collectas.

Tillagd i version 3.3.

Ändrad i version 3.7: Returtypen är nu const char * i stället för char *.

Ändrad i version 3.10: Denna funktion är en del av limited API.

const char *PyUnicode_AsUTF8(PyObject *unicode)

Som PyUnicode_AsUTF8AndSize(), men lagrar inte storleken.

Varning

Denna funktion har inget speciellt beteende för nulltecken som är inbäddade i unicode. Därför kommer strängar som innehåller nolltecken att finnas kvar i den returnerade strängen, vilket vissa C-funktioner kan tolka som slutet på strängen, vilket leder till trunkering. Om trunkering är ett problem rekommenderas det att använda PyUnicode_AsUTF8AndSize() istället.

Tillagd i version 3.3.

Ändrad i version 3.7: Returtypen är nu const char * i stället för char *.

UTF-32 Codecs

Dessa är UTF-32 codec API:er:

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
Returnera värde: Ny referens. En del av Stabil ABI.

Avkodar size byte från en UTF-32-kodad buffertsträng och returnerar motsvarande Unicode-objekt. errors (om inte NULL) definierar felhanteringen. Standardvärdet är ”strict”.

Om byteorder inte är NULL, börjar avkodaren avkodningen med den angivna byteordningen:

*byteorder == -1: liten endian
*byteorder == 0: inbyggd ordning
*byteorder == 1: stor endian

Om *byteorder är noll och de fyra första bytena i indata är en byteordermarkering (BOM), växlar avkodaren till denna byteordning och BOM kopieras inte till den resulterande Unicode-strängen. Om *byteorder är -1 eller 1 kopieras alla byteordermarkeringar till utdata.

Efter slutförandet ställs *byteorder in på den aktuella byteordningen i slutet av indata.

Om byteorder är NULL startar codec i native order-läge.

Returnerar NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
Returnera värde: Ny referens. En del av Stabil ABI.

Om consumed är NULL, uppför sig som PyUnicode_DecodeUTF32(). Om consumed inte är NULL kommer PyUnicode_DecodeUTF32Stateful() inte att behandla efterföljande ofullständiga UTF-32 byte-sekvenser (t.ex. ett antal byte som inte är delbart med fyra) som ett fel. Dessa byte kommer inte att avkodas och antalet byte som har avkodats kommer att lagras i consumed.

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar en Python-bytesträng med UTF-32-kodning i inbyggd byteordning. Strängen börjar alltid med en BOM-markering. Felhanteringen är ”strikt”. Returnera NULL om ett undantag har uppstått i codec.

UTF-16 Codecs

Dessa är UTF-16 codec API:er:

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
Returnera värde: Ny referens. En del av Stabil ABI.

Avkodar size byte från en UTF-16-kodad buffertsträng och returnerar motsvarande Unicode-objekt. errors (om inte NULL) definierar felhanteringen. Standardvärdet är ”strict”.

Om byteorder inte är NULL, börjar avkodaren avkodningen med den angivna byteordningen:

*byteorder == -1: liten endian
*byteorder == 0: inbyggd ordning
*byteorder == 1: stor endian

Om *byteorder är noll och de två första bytena i indata är en byteordermarkering (BOM), växlar avkodaren till denna byteordning och BOM kopieras inte till den resulterande Unicode-strängen. Om *byteorder är -1 eller 1 kopieras alla byteordermarkeringar till utdata (där de resulterar i antingen en ufeff- eller en ufffeff-tecken).

Efter slutförandet ställs *byteorder in på den aktuella byteordningen i slutet av indata.

Om byteorder är NULL startar codec i native order-läge.

Returnerar NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
Returnera värde: Ny referens. En del av Stabil ABI.

Om consumed är NULL, uppför sig som PyUnicode_DecodeUTF16(). Om consumed inte är NULL kommer PyUnicode_DecodeUTF16Stateful() inte att behandla efterföljande ofullständiga UTF-16 byte-sekvenser (t.ex. ett udda antal byte eller ett delat surrogatpar) som ett fel. Dessa byte kommer inte att avkodas och antalet byte som har avkodats kommer att lagras i consumed.

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar en Python-bytesträng med UTF-16-kodning i inbyggd byteordning. Strängen börjar alltid med en BOM-markering. Felhanteringen är ”strikt”. Returnera NULL om ett undantag har uppstått i codec.

UTF-7-codecs

Detta är UTF-7-codec API:er:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den UTF-7-kodade strängen str. Returnera NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Returnera värde: Ny referens. En del av Stabil ABI.

Om consumed är NULL, uppför sig som PyUnicode_DecodeUTF7(). Om consumed inte är NULL, kommer efterföljande ofullständiga UTF-7 base-64 sektioner inte att behandlas som ett fel. Dessa byte kommer inte att avkodas och antalet byte som har avkodats kommer att lagras i consumed.

Unicode-Escape-codecs

Dessa är ”Unicode Escape”-codec API:erna:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den Unicode-Escape-kodade strängen str. Returnerar NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt med Unicode-Escape och returnerar resultatet som ett bytes-objekt. Felhanteringen är ”strikt”. Returnera NULL om ett undantag har uppstått i codec.

Rå-Unikod-Escape Codecs

Detta är API:erna för codec ”Raw Unicode Escape”:

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den Raw-Unicode-Escape-kodade strängen str. Returnera NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt med Raw-Unicode-Escape och returnerar resultatet som ett bytes-objekt. Felhanteringen är ”strikt”. Returnera NULL om ett undantag har uppstått i codec.

Latin-1 Codecs

Detta är API:erna för Latin-1-codec: Latin-1 motsvarar de första 256 Unicode-ordinalerna och endast dessa accepteras av codecs under kodningen.

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den Latin-1-kodade strängen str. Returnera NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt med Latin-1 och returnerar resultatet som ett Python bytes-objekt. Felhanteringen är ”strikt”. Returnera NULL om ett undantag uppstod av codec.

ASCII Codecs

Detta är ASCII-codec-API:erna. Endast 7-bitars ASCII-data accepteras. Alla andra koder genererar fel.

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den ASCII-kodade strängen str. Returnera NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt med ASCII och returnerar resultatet som Python bytes-objekt. Felhanteringen är ”strikt”. Returnera NULL om ett undantag uppstod av codec.

Teckenkartan Codecs

Denna codec är speciell eftersom den kan användas för att implementera många olika codecs (och det är faktiskt vad som gjordes för att få de flesta av de standardcodecs som ingår i paketet encodings). Codec använder mappningar för att koda och avkoda tecken. De mappningsobjekt som tillhandahålls måste stödja __getitem__() mappningsgränssnittet; ordböcker och sekvenser fungerar bra.

Detta är API:erna för mappningskodek:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett Unicode-objekt genom att avkoda size bytes av den kodade strängen str med hjälp av det angivna mapping-objektet. Returnerar NULL om ett undantag har uppstått i codec.

Om mapping är NULL kommer Latin-1-avkodning att tillämpas. Annars måste mapping mappa bytes ordinaler (heltal i intervallet 0 till 255) till Unicode-strängar, heltal (som sedan tolkas som Unicode-ordinaler) eller None. Databytes som inte mappas – sådana som orsakar ett LookupError, liksom sådana som mappas till None, 0xFFFE eller '\ufffe', behandlas som odefinierade mappningar och orsakar ett fel.

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Returnera värde: Ny referens. En del av Stabil ABI.

Kodar ett Unicode-objekt med hjälp av det angivna mapping-objektet och returnerar resultatet som ett bytes-objekt. Felhanteringen är ”strikt”. Returnera NULL om ett undantag har uppstått i codec.

Objektet mapping måste mappa Unicode ordinala heltal till bytesobjekt, heltal i intervallet 0 till 255 eller None. Omappade teckenordinaler (sådana som orsakar ett LookupError) samt mappade till None behandlas som ”odefinierad mappning” och orsakar ett fel.

Följande codec API är speciellt genom att det mappar Unicode till Unicode.

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI.

Översätt en sträng genom att tillämpa en teckenmappningstabell på den och returnera det resulterande Unicode-objektet. Returnera NULL om ett undantag har uppstått i codec.

Mappningstabellen måste mappa Unicodes ordinala heltal till Unicodes ordinala heltal eller None (vilket leder till att tecknet raderas).

Mappningstabeller behöver bara tillhandahålla __getitem__()-gränssnittet; ordböcker och sekvenser fungerar också bra. Omappade teckenordinaler (sådana som orsakar ett LookupError) lämnas orörda och kopieras som de är.

errors har den vanliga betydelsen för codecs. Det kan vara NULL vilket indikerar att standardfelhanteringen ska användas.

MBCS codecs för Windows

Detta är MBCS codec API:er. De är för närvarande endast tillgängliga i Windows och använder Win32 MBCS-omvandlarna för att implementera omvandlingarna. Observera att MBCS (eller DBCS) är en klass av kodningar, inte bara en. Målkodningen definieras av användarinställningarna på den maskin som kör codec:en.

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI on Windows sedan version 3.7.

Skapa ett Unicode-objekt genom att avkoda size bytes av den MBCS-kodade strängen str. Returnera NULL om ett undantag har uppstått i codec.

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Returnera värde: Ny referens. En del av Stabil ABI on Windows sedan version 3.7.

Om consumed är NULL, uppför sig som PyUnicode_DecodeMBCS(). Om consumed inte är NULL, kommer PyUnicode_DecodeMBCSStateful() inte att avkoda trailing lead byte och antalet byte som har avkodats kommer att lagras i consumed.

PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
Returnera värde: Ny referens. En del av Stabil ABI on Windows sedan version 3.7.

Liknar PyUnicode_DecodeMBCSStateful(), men använder den kodsida som anges av code_page.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)
Returnera värde: Ny referens. En del av Stabil ABI on Windows sedan version 3.7.

Kodar ett Unicode-objekt med MBCS och returnerar resultatet som Python bytes-objekt. Felhanteringen är ”strikt”. Returnera NULL om ett undantag uppstod av codec.

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
Returnera värde: Ny referens. En del av Stabil ABI on Windows sedan version 3.7.

Kodar Unicode-objektet med hjälp av den angivna kodsidan och returnerar ett Python bytes-objekt. Returnera NULL om ett undantag uppstod av codec. Använd kodsidan CP_ACP för att hämta MBCS-kodaren.

Tillagd i version 3.3.

Metoder och slotfunktioner

Följande API:er kan hantera Unicode-objekt och strängar som indata (vi refererar till dem som strängar i beskrivningarna) och returnera Unicode-objekt eller heltal på lämpligt sätt.

De returnerar alla NULL eller -1 om ett undantag inträffar.

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)
Returnera värde: Ny referens. En del av Stabil ABI.

Concat två strängar som ger en ny Unicode-sträng.

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
Returnera värde: Ny referens. En del av Stabil ABI.

Delar en sträng som ger en lista med Unicode-strängar. Om sep är NULL kommer uppdelning att göras vid alla substrängar med blanksteg. Annars sker uppdelningen vid den angivna separatorn. Högst maxsplit uppdelningar kommer att göras. Om värdet är negativt sätts ingen gräns. Separatorer inkluderas inte i den resulterande listan.

Vid fel returneras NULL med en undantagsuppsättning.

Motsvarar str.split().

PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
Returnera värde: Ny referens. En del av Stabil ABI.

Liknar PyUnicode_Split(), men uppdelningen görs från slutet av strängen.

Vid fel returneras NULL med en undantagsuppsättning.

Motsvarar str.rsplit().

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)
Returnera värde: Ny referens. En del av Stabil ABI.

Dela en Unicode-sträng vid radbrytningar och returnera en lista med Unicode-strängar. CRLF anses vara en radbrytning. Om keepends är 0 inkluderas inte radbrytningstecken i de resulterande strängarna.

PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)
Returnera värde: Ny referens. En del av Stabil ABI.

Dela en Unicode-sträng vid den första förekomsten av sep och returnera en 3-tupel som innehåller delen före separatorn, själva separatorn och delen efter separatorn. Om separatorn inte hittas returneras en 3-tupel som innehåller själva strängen, följt av två tomma strängar.

sep får inte vara tomt.

Vid fel returneras NULL med en undantagsuppsättning.

Motsvarar str.partition().

PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)
Returnera värde: Ny referens. En del av Stabil ABI.

Liknar PyUnicode_Partition(), men delar upp en Unicode-sträng vid den sista förekomsten av sep. Om separatorn inte hittas returneras en 3-tupel som innehåller två tomma strängar, följt av själva strängen.

sep får inte vara tomt.

Vid fel returneras NULL med en undantagsuppsättning.

Motsvarar str.rpartition().

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)
Returnera värde: Ny referens. En del av Stabil ABI.

Sammanfoga en sekvens av strängar med hjälp av den angivna separatorn och returnera den resulterande Unicode-strängen.

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
En del av Stabil ABI.

Returnerar 1 om substr matchar unicode[start:end] vid den angivna svansänden (direction == -1 betyder att man gör en prefixmatchning, direction == 1 en suffixmatchning), 0 annars. Returnerar -1 om ett fel inträffade.

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
En del av Stabil ABI.

Returnerar den första positionen för substr i unicode[start:end] med hjälp av den angivna direction (direction == 1 betyder att man gör en framåtriktad sökning, direction == -1 en bakåtriktad sökning). Returvärdet är index för den första matchningen; ett värde på -1 indikerar att ingen matchning hittades och -2 indikerar att ett fel inträffade och att ett undantag har ställts in.

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)
En del av Stabil ABI sedan version 3.7.

Returnerar den första positionen för tecknet ch i unicode[start:end] med hjälp av den angivna direction (direction == 1 betyder att man gör en framåtriktad sökning, direction == -1 en bakåtriktad sökning). Returvärdet är index för den första matchningen; ett värde på -1 indikerar att ingen matchning hittades och -2 indikerar att ett fel inträffade och att ett undantag har ställts in.

Tillagd i version 3.3.

Ändrad i version 3.7: start och end är nu justerade för att bete sig som unicode[start:end].

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
En del av Stabil ABI.

Returnerar antalet icke-överlappande förekomster av substr i unicode[start:end]. Returnera -1 om ett fel inträffade.

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
Returnera värde: Ny referens. En del av Stabil ABI.

Ersätt högst maxcount förekomster av substr i unicode med replstr och returnera det resulterande Unicode-objektet. maxcount == -1 innebär att alla förekomster ersätts.

int PyUnicode_Compare(PyObject *left, PyObject *right)
En del av Stabil ABI.

Jämför två strängar och returnera -1, 0, 1 för mindre än, lika med respektive större än.

Denna funktion returnerar -1 om den misslyckas, så man bör anropa PyErr_Occurred() för att kontrollera om det finns fel.

Se även

Funktionen PyUnicode_Equal().

int PyUnicode_Equal(PyObject *a, PyObject *b)
En del av Stabil ABI sedan version 3.14.

Testar om två strängar är lika:

  • Returnerar 1 om a är lika med b.

  • Returnerar 0 om a inte är lika med b.

  • Ställ in ett TypeError-undantag och returnera -1 om a eller b inte är ett str-objekt.

Funktionen lyckas alltid om a och b är str-objekt.

Funktionen fungerar för underklasserna str, men inte för den anpassade metoden __eq__().

Se även

Funktionen PyUnicode_Compare().

Tillagd i version 3.14.

int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)
En del av Stabil ABI sedan version 3.13.

Jämför ett Unicode-objekt med en char-buffert som tolkas som UTF-8- eller ASCII-kodad och returnerar true (1) om de är lika, eller false (0) annars. Om Unicode-objektet innehåller surrogatkodpunkter (U+D800 - U+DFFF) eller om C-strängen inte är giltig UTF-8, returneras false (0).

Denna funktion ger inte upphov till undantag.

Tillagd i version 3.13.

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)
En del av Stabil ABI sedan version 3.13.

Liknar PyUnicode_EqualToUTF8AndSize(), men beräknar strängens längd med hjälp av strlen(). Om Unicode-objektet innehåller null-tecken returneras false (0).

Tillagd i version 3.13.

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)
En del av Stabil ABI.

Jämför ett Unicode-objekt, unicode, med sträng och returnerar -1, 0, 1 för mindre än, lika med respektive större än. Det är bäst att bara skicka ASCII-kodade strängar, men funktionen tolkar indatasträngen som ISO-8859-1 om den innehåller icke-ASCII-tecken.

Denna funktion ger inte upphov till undantag.

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
Returnera värde: Ny referens. En del av Stabil ABI.

Rich jämför två Unicode-strängar och returnerar något av följande:

Möjliga värden för op är Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT och Py_LE.

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)
Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar ett nytt strängobjekt från format och args; detta är analogt med format % args.

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)
En del av Stabil ABI.

Kontrollera om substr ingår i unicode och returnera true eller false i enlighet med detta.

substr måste sammanfogas till en Unicode-sträng med ett element. -1 returneras om det uppstod ett fel.

void PyUnicode_InternInPlace(PyObject **p_unicode)
En del av Stabil ABI.

Internerar argumentet *p_unicode på plats. Argumentet måste vara adressen till en pekarvariabel som pekar på ett Python Unicode-strängobjekt. Om det finns en befintlig internerad sträng som är samma som *p_unicode, sätter den *p_unicode till den (släpper referensen till det gamla strängobjektet och skapar en ny strong reference till det internerade strängobjektet), annars lämnar den *p_unicode ensam och internerar den.

(Förtydligande: även om det talas mycket om referenser, tänk på denna funktion som referensneutral. Du måste äga objektet du skickar in; efter anropet äger du inte längre den skickade referensen, men du äger nyligen resultatet)

Denna funktion ger aldrig upphov till ett undantag. Vid fel lämnar den sitt argument oförändrat utan att ingripa i det.

Instanser av underklasser till str får inte internaliseras, det vill säga PyUnicode_CheckExact(*p_unicode) måste vara sant. Om så inte är fallet lämnas argumentet oförändrat, precis som med alla andra fel.

Observera att internerade strängar inte är ”odödliga”. Du måste behålla en referens till resultatet för att dra nytta av interning.

PyObject *PyUnicode_InternFromString(const char *str)
Returnera värde: Ny referens. En del av Stabil ABI.

En kombination av PyUnicode_FromString() och PyUnicode_InternInPlace(), avsedd för statiskt allokerade strängar.

Returnerar en ny (”ägd”) referens till antingen ett nytt Unicode-strängobjekt som har internaliserats eller ett tidigare internaliserat strängobjekt med samma värde.

Python kan behålla en referens till resultatet, eller göra det immortal, vilket förhindrar att det omedelbart samlas in i skräp. För internering av ett obegränsat antal olika strängar, till exempel sådana som kommer från användarinmatning, föredrar du att anropa PyUnicode_FromString() och PyUnicode_InternInPlace() direkt.

unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)

Returnerar ett värde som inte är noll om str är internerad, noll annars. Argumentet str måste vara en sträng; detta kontrolleras inte. Denna funktion lyckas alltid.

Ett returvärde som inte är noll kan innehålla ytterligare information om hur strängen är internaliserad. Betydelsen av sådana icke-nollvärden, liksom varje specifik strängs internrelaterade detaljer, kan ändras mellan CPython-versioner.

PyUnicodeSkribent

API:et PyUnicodeWriter kan användas för att skapa ett Python str-objekt.

Tillagd i version 3.14.

type PyUnicodeWriter

En instans för Unicode-skrivare.

Instansen måste förstöras av PyUnicodeWriter_Finish() vid framgång, eller PyUnicodeWriter_Discard() vid fel.

PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)

Skapa en Unicode-skrivarinstans.

length måste vara större än eller lika med 0.

Om length är större än 0, allokeras en intern buffert med length tecken.

Ställ in ett undantag och returnera NULL vid fel.

PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)

Returnerar det slutliga Python str-objektet och förstör skrivarinstansen.

Ställ in ett undantag och returnera NULL vid fel.

Skrivarinstansen är ogiltig efter detta anrop.

void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)

Kassera den interna Unicode-bufferten och förstör skrivarinstansen.

Om writer är NULL utförs ingen åtgärd.

Skrivarinstansen är ogiltig efter detta anrop.

int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)

Skriv det enskilda Unicode-tecknet ch till writer.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

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

Avkoda strängen str från UTF-8 i strikt läge och skriv utdata till writer.

size är strängens längd i byte. Om size är lika med -1, anropa strlen(str) för att få fram strängens längd.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

Se även PyUnicodeWriter_DecodeUTF8Stateful().

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

Skriv ASCII-strängen str till writer.

size är strängens längd i byte. Om size är lika med -1, anropa strlen(str) för att få fram strängens längd.

str får endast innehålla ASCII-tecken. Beteendet är odefinierat om str innehåller icke-ASCII-tecken.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

Tillagd i version 3.14.

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

Skriv den breda strängen str till writer.

size är ett antal breda tecken. Om size är lika med -1, anropa wcslen(str) för att få fram strängens längd.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

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

Skriv UCS4-strängen str till writer.

size är ett antal UCS4-tecken.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)

Anropa PyObject_Str() på obj och skriv utdata till writer.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)

Anropa PyObject_Repr() på obj och skriv utdata till writer.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

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

Skriv in delsträngen str[start:end] i writer.

str måste vara Python str-objekt. start måste vara större än eller lika med 0, och mindre än eller lika med end. end måste vara mindre än eller lika med str längd.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

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

Liknar PyUnicode_FromFormat(), men skriver utdata direkt till writer.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

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

Avkoda strängen str från UTF-8 med felhanteraren errors och skriv utdata till writer.

size är strängens längd i byte. Om size är lika med -1, anropa strlen(str) för att få fram strängens längd.

errors är ett felhanterare namn, som till exempel "replace". Om errors är NULL används den strikta felhanteringen.

Om consumed inte är NULL, sätt *consumed till antalet avkodade byte vid framgång. Om consumed är NULL, behandlas efterföljande ofullständiga UTF-8 byte-sekvenser som ett fel.

Vid framgång returneras 0. Vid fel, sätt ett undantag, lämna skrivaren oförändrad och returnera -1.

Se även PyUnicodeWriter_WriteUTF8().

Föråldrad API

Följande API är föråldrat.

type Py_UNICODE

Detta är en typdefinition av wchar_t, som är en 16-bitars typ eller 32-bitars typ beroende på plattform. Använd wchar_t direkt istället.

Ändrad i version 3.3: I tidigare versioner var detta en 16-bitars typ eller en 32-bitars typ beroende på om du valde en ”smal” eller ”bred” Unicode-version av Python vid byggtiden.

Deprecated since version 3.13, will be removed in version 3.15.

int PyUnicode_READY(PyObject *unicode)

Gör ingenting och returnerar 0. Detta API behålls endast för bakåtkompatibilitet, men det finns inga planer på att ta bort det.

Tillagd i version 3.3.

Föråldrad sedan version 3.10: Detta API gör ingenting sedan Python 3.12. Tidigare behövde detta anropas för varje sträng som skapades med det gamla API:et (PyUnicode_FromUnicode() eller liknande).

unsigned int PyUnicode_IS_READY(PyObject *unicode)

Gör ingenting och returnera 1. Detta API behålls endast för bakåtkompatibilitet, men det finns inga planer på att ta bort det.

Tillagd i version 3.3.

Föråldrad sedan version 3.14: Detta API gör ingenting sedan Python 3.12. Tidigare kunde detta anropas för att kontrollera om PyUnicode_READY() är nödvändigt.