Conversão de Strings e Formação

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, ...)

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

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

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

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 e format != NULL.

If the platform doesn’t have vsnprintf() and the buffer size needed to avoid truncation exceeds size by more than 512 bytes, Python aborts with a Py_FatalError.

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, “aconteceu algo de errado.” 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.

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

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.

If endptr is NULL, convert the whole string. Raise ValueError and return -1.0 if the string is not a valid representation of a floating-point number.

Se endptr não for NULL, converte o máximo possível da string e defina *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 retorne -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; levantar essa exceção e retornar -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.

Novo na versão 3.1.

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

Converte um double val 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 can be zero or more of the values Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, or Py_DTSF_ALT, or-ed together:

  • Py_DTSF_SIGN means to always precede the returned string with a sign character, even if val is non-negative.

  • Py_DTSF_ADD_DOT_0 means to ensure that the returned string will not look like an integer.

  • Py_DTSF_ALT means to apply “alternate” formatting rules. See the documentation for the PyOS_snprintf() '#' specifier for details.

If ptype is non-NULL, then the value it points to will be set to one of Py_DTST_FINITE, Py_DTST_INFINITE, or Py_DTST_NAN, signifying that val is a finite number, an infinite number, or not a number, respectively.

The return value is a pointer to buffer with the converted string or NULL if the conversion failed. The caller is responsible for freeing the returned string by calling PyMem_Free().

Novo na versão 3.1.

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

Comparação de strings sem diferença entre maiúsculas e minúsculas. A função funciona quase de forma idêntica a strcmp() exceto que ignora o caso.

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

Comparação de strings sem diferença entre maiúsculas e minúsculas. A função funciona quase de forma idêntica a strncmp() exceto que ignora o caso.