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.
