# 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.