Conversión y formato de cadenas de caracteres
*********************************************

Funciones para conversión de números y salida de cadena de caracteres
formateadas.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
    * Part of the Stable ABI.*

   Salida de no más de *size* bytes a *str* según la cadena de
   caracteres de formato *format* y los argumentos adicionales.
   Consulte la página de manual de Unix *snprintf(3)*.

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
    * Part of the Stable ABI.*

   Salida de no más de *size* bytes a *str* según la cadena de
   caracteres de formato *format* y la lista de argumentos variables
   *va*. Página de manual de Unix *vsnprintf(3)*.

"PyOS_snprintf()" y "PyOS_vsnprintf()" envuelven las funciones
estándar de la biblioteca C "snprintf()" y "vsnprintf()". Su propósito
es garantizar un comportamiento consistente en casos de esquina
(*corner cases*), que las funciones del Estándar C no hacen.

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", "format != NULL" and "size < INT_MAX". Note that this means there
is no equivalent to the C99 "n = snprintf(NULL, 0, ...)" which would
determine the necessary buffer size.

El valor de retorno (*rv*) para estas funciones debe interpretarse de
la siguiente manera:

* Cuando "0 <= rv < size", la conversión de salida fue exitosa y los
  caracteres *rv* se escribieron en *str* (excluyendo el byte "'\0'"
  final en "str[rv]").

* Cuando "rv >= size", la conversión de salida se truncó y se habría
  necesitado un búfer con "rv + 1" bytes para tener éxito.
  "str[size-1]" es "'\0'" en este caso.

* Cuando "rv < 0", "sucedió algo malo". "str[size-1]" es "'\0'" en
  este caso también, pero el resto de *str* no está definido. La causa
  exacta del error depende de la plataforma subyacente.

Las siguientes funciones proporcionan cadenas de caracteres
independientes de la configuración regional para numerar las
conversiones.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)
    * Part of the Stable ABI.*

   Convert the initial part of the string in "str" to an unsigned long
   value according to the given "base", which must be between "2" and
   "36" inclusive, or be the special value "0".

   Leading white space and case of characters are ignored.  If "base"
   is zero it looks for a leading "0b", "0o" or "0x" to tell which
   base.  If these are absent it defaults to "10".  Base must be 0 or
   between 2 and 36 (inclusive).  If "ptr" is non-"NULL" it will
   contain a pointer to the end of the scan.

   If the converted value falls out of range of corresponding return
   type, range error occurs ("errno" is set to "ERANGE") and
   "ULONG_MAX" is returned.  If no conversion can be performed, "0" is
   returned.

   See also the Unix man page *strtoul(3)*.

   Nuevo en la versión 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)
    * Part of the Stable ABI.*

   Convert the initial part of the string in "str" to an long value
   according to the given "base", which must be between "2" and "36"
   inclusive, or be the special value "0".

   Same as "PyOS_strtoul()", but return a long value instead and
   "LONG_MAX" on overflows.

   See also the Unix man page *strtol(3)*.

   Nuevo en la versión 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
    * Part of the Stable ABI.*

   Convert a string "s" to a double, raising a Python exception on
   failure.  The set of accepted strings corresponds to the set of
   strings accepted by Python's "float()" constructor, except that "s"
   must not have leading or trailing whitespace. The conversion is
   independent of the current locale.

   Si "endptr" es "NULL", convierte toda la cadena de caracteres.
   Lanza "ValueError" y retorna "-1.0" si la cadena de caracteres no
   es una representación válida de un número de punto flotante.

   Si *endptr* no es "NULL", convierte la mayor cantidad posible de la
   cadena de caracteres y configura "*endptr" para que apunte al
   primer carácter no convertido. Si ningún segmento inicial de la
   cadena de caracteres es la representación válida de un número de
   punto flotante, configura "*endptr" para que apunte al comienzo de
   la cadena de caracteres, lanza ValueError y retorna "-1.0".

   Si "s" representa un valor que es demasiado grande para almacenar
   en un flotante (por ejemplo, ""1e500"" es una cadena de caracteres
   de este tipo en muchas plataformas), entonces si
   "overflow_exception" es "NULL" retorna "Py_HUGE_VAL" (con un signo
   apropiado) y no establece ninguna excepción. De lo contrario,
   "overflow_exception" debe apuntar a un objeto excepción de Python;
   lanza esa excepción y retorna "-1.0". En ambos casos, configura
   "*endptr" para que apunte al primer carácter después del valor
   convertido.

   Si se produce algún otro error durante la conversión (por ejemplo,
   un error de falta de memoria), establece la excepción Python
   adecuada y retorna "-1.0".

   Nuevo en la versión 3.1.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
    * Part of the Stable ABI.*

   Convert a double *val* to a string using supplied *format_code*,
   *precision*, and *flags*.

   *format_code*  debe ser uno de "'e'", "'E'", "'f'", "'F'", "'g'",
   "'G'" or "'r'".  Para "'r'", la *precision* suministrada debe ser 0
   y se ignora.  El código de formato "'r'" especifica el formato
   estándar "repr()".

   *flags* puede ser cero o más de los valores "Py_DTSF_SIGN",
   "Py_DTSF_ADD_DOT_0", o "Py_DTSF_ALT", unidos por *or* (*or-ed*)
   juntos:

   * "Py_DTSF_SIGN" significa preceder siempre a la cadena de
     caracteres retornada con un carácter de signo, incluso si *val*
     no es negativo.

   * "Py_DTSF_ADD_DOT_0" significa asegurarse de que la cadena de
     caracteres retornada no se verá como un número entero.

   * "Py_DTSF_ALT" significa aplicar reglas de formato "alternativas".
     Consulte la documentación del especificador "PyOS_snprintf()"
     "'#'" para obtener más detalles.

   Si *ptype* no es "NULL", el valor al que apunta se establecerá en
   uno de "Py_DTST_FINITE", "Py_DTST_INFINITE" o "Py_DTST_NAN", lo que
   significa que *val* es un número finito, un número infinito o no es
   un número, respectivamente.

   El valor de retorno es un puntero a *buffer* con la cadena de
   caracteres convertida o "NULL" si la conversión falla. La persona
   que llama es responsable de liberar la cadena de caracteres
   retornada llamando a "PyMem_Free()".

   Nuevo en la versión 3.1.

int PyOS_stricmp(const char *s1, const char *s2)

   Case insensitive comparison of strings. The function works almost
   identically to "strcmp()" except that it ignores the case.

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

   Case insensitive comparison of strings. The function works almost
   identically to "strncmp()" except that it ignores the case.
