Conversão e formação de strings

Funções para conversão de números e saída formatada de strings.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
Parte da ABI Estável.

Saída não superior a size bytes para str de acordo com a string de formato format e os argumentos extras. Veja a página man do Unix snprintf(3).

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
Parte da ABI Estável.

Saída não superior a size bytes para str de acordo com o string de formato format e a variável argumento de lista va. Página man do Unix vsnprintf(3).

PyOS_snprintf() e PyOS_vsnprintf() envolvem as funções snprintf() e vsnprintf() da biblioteca Standard C. Seu objetivo é garantir um comportamento consistente em casos extremos, o que as funções do Standard C não garantem.

Os invólucros garantem que str[size-1] seja sempre '\0' no retorno. Eles nunca escrevem mais do que size bytes (incluindo o '\0' ao final) em str. Ambas as funções exigem que str != NULL, size > 0, format != NULL e size < INT_MAX. Note que isso significa que não há equivalente ao n = snprintf(NULL, 0, ...) do C99 que determinaria o tamanho de buffer necessário.

O valor de retorno (rv) para essas funções deve ser interpretado da seguinte forma:

  • Quando 0 <= rv < size, a conversão de saída foi bem-sucedida e os caracteres de rv foram escritos em str (excluindo o '\0' byte em str[rv]).

  • Quando rv >= size, a conversão de saída foi truncada e um buffer com rv + 1 bytes teria sido necessário para ter sucesso. str[size-1] é '\0' neste caso.

  • Quando rv < 0, a conversão da saída falhou e str[size-1] é '\0' neste caso também, mas o resto de str é indefinido. A causa exata do erro depende da plataforma subjacente.

As funções a seguir fornecem strings independentes de localidade para conversões de números.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)
Parte da ABI Estável.

Converte a parte inicial da string em str para um valor unsigned long de acordo com a base fornecida, que deve estar entre 2 e 36 inclusive, ou ser o valor especial 0.

Espaços em branco iniciais e diferenciação entre caracteres maiúsculos e minúsculos são ignorados. Se base for zero, procura um 0b, 0o ou 0x inicial para informar qual base. Se estes estiverem ausentes, o padrão é 10. Base deve ser 0 ou entre 2 e 36 (inclusive). Se ptr não for NULL, conterá um ponteiro para o fim da varredura.

Se o valor convertido ficar fora do intervalo do tipo de retorno correspondente, ocorrerá um erro de intervalo (errno é definido como ERANGE) e ULONG_MAX será retornado. Se nenhuma conversão puder ser realizada, 0 será retornado.

Veja também a página man do Unix strtoul(3).

Adicionado na versão 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)
Parte da ABI Estável.

Converte a parte inicial da string em str para um valor long de acordo com a base fornecida, que deve estar entre 2 e 36 inclusive, ou ser o valor especial 0.

O mesmo que PyOS_strtoul(), mas retorna um valor long e LONG_MAX em caso de estouro.

Veja também a página man do Unix strtol(3).

Adicionado na versão 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
Parte da ABI Estável.

Converte uma string s em double, levantando uma exceção Python em caso de falha. O conjunto de strings aceitas corresponde ao conjunto de strings aceito pelo construtor float() do Python, exceto que s não deve ter espaços em branco à esquerda ou à direita. A conversão é independente da localidade atual.

Se endptr for NULL, converte a string inteira. Levanta ValueError e retorna -1.0 se a string não for uma representação válida de um número de ponto flutuante.

Se endptr não for NULL, converte o máximo possível da string e define *endptr para apontar para o primeiro caractere não convertido. Se nenhum segmento inicial da string for a representação válida de um número de ponto flutuante, define *endptr para apontar para o início da string, levanta ValueError e retorna -1.0.

Se s representa um valor que é muito grande para armazenar em um ponto flutuante (por exemplo, "1e500" é uma string assim em muitas plataformas), então se overflow_exception for NULL retorna Py_HUGE_VAL (com um sinal apropriado) e não define nenhuma exceção. Caso contrário, overflow_exception deve apontar para um objeto de exceção Python; levanta essa exceção e retorna -1.0. Em ambos os casos, define *endptr para apontar para o primeiro caractere após o valor convertido.

Se qualquer outro erro ocorrer durante a conversão (por exemplo, um erro de falta de memória), define a exceção Python apropriada e retorna -1.0.

Adicionado na versão 3.1.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
Parte da ABI Estável.

Converte um val double para uma string usando format_code, precision e flags fornecidos.

format_code deve ser um entre 'e', 'E', 'f', 'F', 'g', 'G' ou 'r'. Para 'r', a precisão precision fornecida deve ser 0 e é ignorada. O código de formato 'r' especifica o formato padrão de repr().

flags podem ser zero ou mais dos seguintes valores combinados por meio do operador OR:

Py_DTSF_SIGN

Sempre preceda a string retornada com um caractere de sinal, mesmo que val não seja negativo.

Py_DTSF_ADD_DOT_0

Garante que a string retornada não se pareça com um número inteiro.

Py_DTSF_ALT

Aplica as regras de formatação “alternativas”. Veja a documentação para o especificador '#' de PyOS_snprintf() para detalhes.

Py_DTSF_NO_NEG_0

Zero negativo é convertido para zerp positivo.

Adicionado na versão 3.11.

Se type não for NULL, então o valor para o qual ele aponta será definido como um dos Py_DTST_FINITE, Py_DTST_INFINITE ou Py_DTST_NAN, significando que val é um número finito, um número infinito ou não um número, respectivamente.

O valor de retorno é um ponteiro para buffer com a string convertida ou NULL se a conversão falhou. O chamador é responsável por liberar a string retornada chamando PyMem_Free().

Adicionado na versão 3.1.

int PyOS_mystricmp(const char *str1, const char *str2)
int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)
Parte da ABI Estável.

Comparação de strings sem distinção entre maiúsculas e minúsculas. Essas funções funcionam de maneira quase idêntica a strcmp() e strncmp() (respectivamente), exceto pelo fato de ignorarem maiúsculas e minúsculas em caracteres ASCII.

Retorna 0 se as strings forem iguais, um valor negativo se str1 for ordenada lexicograficamente antes de str2, ou um valor positivo se for ordenada depois.

Nos argumentos str1 ou str2, um byte NUL marca o fim da string. Para PyOS_mystrnicmp(), o argumento size fornece o tamanho máximo da string, como se NUL estivesse presente no índice fornecido por size.

Estas funções não usam a localidade.

int PyOS_stricmp(const char *str1, const char *str2)
int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)

Comparação de strings sem distinção entre maiúsculas e minúsculas.

No Windows, estes são apelidos de stricmp() e strnicmp(), respectivamente.

Em outras plataformas, são apelidos de PyOS_mystricmp() e PyOS_mystrnicmp(), respectivamente.

Classificação e conversão de caracteres

As macros a seguir fornecem classificação e conversão de caracteres independentes de localidade (ao contrário da biblioteca padrão C ctype.h). O argumento deve ser um char com ou sem sinal.

Py_ISALNUM(c)

Retorna verdadeiro se o caractere c for um caractere alfanumérico.

Py_ISALPHA(c)

Retorna verdadeiro se o caractere c for um caractere alfabético (a-z e A-Z).

Py_ISDIGIT(c)

Retorna verdadeiro se o caractere c for um dígito decimal (0-9).

Py_ISLOWER(c)

Retorna verdadeiro se o caractere c for uma letra minúscula do ASCII (a-z).

Py_ISUPPER(c)

Retorna verdadeiro se o caractere c for uma letra maiúscula do ASCII (A-Z).

Py_ISSPACE(c)

Retorna verdadeiro se o caractere c for um caractere de espaço em branco (espaço, tabulação, retorno de carro, nova linha, tabulação vertical ou alimentação de formulário).

Py_ISXDIGIT(c)

Retorna verdadeiro se o caractere c for um dígito hexadecimal (0-9, a-f e A-F).

Py_TOLOWER(c)

Retorna o equivalente em minúsculas do caractere c.

Py_TOUPPER(c)

Retorna o equivalente em maiúsculas do caractere c.