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.
