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

  Output not more than size bytes to str according to the format string format and the extra arguments. See the Unix man page snprintf(3).

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

  Output not more than size bytes to str according to the format string format and the variable argument list va. Unix man page 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.

The wrappers ensure that `str[size-1]` is always `'\0'` upon return. They never write more than size bytes (including the trailing `'\0'`) into str. Both functions require that `str != NULL`, `size > 0` and `format != NULL`.

Se a plataforma não tiver `vsnprintf()` e o tamanho do buffer necessário para evitar o truncamento exceder size em mais de 512 bytes, o Python aborta com um `Py_FatalError()`.

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

- When `0 <= rv < size`, the output conversion was successful and rv characters were written to str (excluding the trailing `'\0'` byte at `str[rv]`).

- When `rv >= size`, the output conversion was truncated and a buffer with `rv + 1` bytes would have been needed to succeed. `str[size-1]` is `'\0'` in this case.

- When `rv < 0`, “something bad happened.” `str[size-1]` is `'\0'` in this case too, but the rest of str is undefined. The exact cause of the error depends on the underlying platform.

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.

  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 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 pode ser zero ou mais de valores `Py_DTSF_SIGN`, `Py_DTSF_ADD_DOT_0` ou `Py_DTSF_ALT`, alternados por operador lógico OU:

  - `Py_DTSF_SIGN` significa sempre preceder a string retornada com um caractere de sinal, mesmo se val não for negativo.

  - `Py_DTSF_ADD_DOT_0` significa garantir que a string retornada não se pareça com um inteiro.

  - `Py_DTSF_ALT` significa aplicar regras de formatação “alternativas”. Veja a documentação para o especificador `'#'` de `PyOS_snprintf()` para detalhes.

  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()`.

  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.