# 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`, “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.

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

  Adicionado 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 a diferença entre maiúsculas e minúsculas.

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 a diferença entre maiúsculas e minúsculas.