Konvertering och formatering av strängar

Funktioner för nummerkonvertering och formaterad strängutmatning.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
En del av Stabil ABI.

Skriver ut högst storlek byte till str enligt formatsträngen format och de extra argumenten. Se Unix man-sida snprintf(3).

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
En del av Stabil ABI.

Skriver ut högst storlek byte till str enligt formatsträngen format och variabelargumentlistan va. Unix man page vsnprintf(3).

PyOS_snprintf() och PyOS_vsnprintf() omsluter Standard C-biblioteksfunktionerna snprintf() och vsnprintf(). Deras syfte är att garantera konsekvent beteende i hörnfall, vilket Standard C-funktionerna inte gör.

Omslagen ser till att str[size-1] alltid är '\0' vid retur. De skriver aldrig mer än size bytes (inklusive den efterföljande '\0') till str. Båda funktionerna kräver att str != NULL, size > 0, format != NULL och size < INT_MAX. Observera att detta innebär att det inte finns någon motsvarighet till C99 n = snprintf(NULL, 0, ...) som skulle bestämma den nödvändiga buffertstorleken.

Returvärdet (rv) för dessa funktioner ska tolkas på följande sätt:

  • När 0 <= rv < size, var utdatakonverteringen lyckad och rv tecken skrevs till str (exklusive den avslutande byten '\0' vid str[rv]).

  • När rv >= size, blev utdatakonverteringen avkortad och en buffert med rv + 1 bytes skulle ha behövts för att lyckas. str[size-1] är '\0' i det här fallet.

  • När rv < 0, ”hände något dåligt.” str[size-1] är '\0' även i detta fall, men resten av str är odefinierat. Den exakta orsaken till felet beror på den underliggande plattformen.

Följande funktioner ger lokaloberoende omvandling av strängar till tal.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)
En del av Stabil ABI.

Konverterar den inledande delen av strängen i str till ett unsigned long-värde enligt den angivna base, som måste vara mellan 2 och 36 inklusive, eller vara specialvärdet 0.

Ledande blanksteg och skiftande tecken ignoreras. Om base är noll letar den efter en ledande 0b, 0o eller 0x för att avgöra vilken bas. Om dessa saknas är standardvärdet 10. Basen måste vara 0 eller mellan 2 och 36 (inklusive). Om ptr är icke-NULL kommer den att innehålla en pekare till slutet av skanningen.

Om det konverterade värdet faller utanför intervallet för motsvarande returtyp, uppstår ett intervallfel (errno sätts till ERANGE) och ULONG_MAX returneras. Om ingen konvertering kan utföras returneras 0.

Se även Unix man page strtoul(3).

Tillagd i version 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)
En del av Stabil ABI.

Konverterar den inledande delen av strängen i str till ett long-värde enligt den angivna base, som måste vara mellan 2 och 36 inklusive, eller vara specialvärdet 0.

Samma som PyOS_strtoul(), men returnerar ett long-värde istället och LONG_MAX vid överskridanden.

Se även Unix man page strtol(3).

Tillagd i version 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
En del av Stabil ABI.

Konverterar en sträng s till en double, med ett Python-undantag om det misslyckas. Uppsättningen av accepterade strängar motsvarar uppsättningen av strängar som accepteras av Pythons float()-konstruktör, förutom att s inte får ha ledande eller efterföljande blanksteg. Konverteringen är oberoende av aktuell locale.

Om endptr är NULL, konvertera hela strängen. Utlös ValueError och returnera \-1.0 om strängen inte är en giltig representation av ett flyttal.

Om endptr inte är NULL, konvertera så mycket som möjligt av strängen och sätt *endptr till att peka på det första okonverterade tecknet. Om inget inledande segment av strängen är en giltig representation av ett flyttal, sätt *endptr till att peka på början av strängen, skapa ValueError och returnera \-1.0.

Om s representerar ett värde som är för stort för att lagras i ett float (till exempel är "1e500" en sådan sträng på många plattformar) och om overflow_exception är NULL, returnera Py_INFINITY (med lämpligt tecken) och ställ inte in någon undantag. I annat fall måste overflow_exception peka på ett Python-undantagsobjekt; generera det undantaget och returnera \-1.0. I båda fallen ska *endptr ställas in så att den pekar på det första tecknet efter det konverterade värdet.

Om något annat fel inträffar under konverteringen (t.ex. ett fel som innebär att minnet är slut), ska du ange lämpligt Python-undantag och returnera \-1.0.

Tillagd i version 3.1.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
En del av Stabil ABI.

Konverterar en double val till en sträng med hjälp av angiven format_code, precision och flags.

format_code måste vara en av 'e', 'E', 'f', 'F', 'g', 'G' eller 'r'. För 'r' måste den medföljande precisionen vara 0 och ignoreras. Formatkoden 'r' specificerar standardformatet repr().

flags kan vara noll eller flera av värdena Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, eller Py_DTSF_ALT, eller kombinerade:

  • Py_DTSF_SIGN innebär att den returnerade strängen alltid ska föregås av ett tecken, även om val är icke-negativt.

  • Py_DTSF_ADD_DOT_0 innebär att man säkerställer att den returnerade strängen inte ser ut som ett heltal.

  • Py_DTSF_ALT innebär att tillämpa ”alternativa” formateringsregler. Se dokumentationen för specificeraren PyOS_snprintf() '#' för mer information.

Om ptype inte är NULL kommer värdet som den pekar på att sättas till ett av Py_DTST_FINITE, Py_DTST_INFINITE eller Py_DTST_NAN, vilket betyder att val är ett ändligt tal, ett oändligt tal eller inte ett tal.

Returvärdet är en pekare till buffer med den konverterade strängen eller NULL om konverteringen misslyckades. Anroparen är ansvarig för att frigöra den returnerade strängen genom att anropa PyMem_Free().

Tillagd i version 3.1.

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

Jämförelse av strängar utan hänsyn till skiftlägesskillnader. Funktionen fungerar nästan identiskt med strcmp() förutom att den ignorerar skiftlägesangivelser.

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

Jämförelse av strängar utan hänsyn till skiftlägesskillnader. Funktionen fungerar nästan identiskt med strncmp() förutom att den ignorerar versaler.