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

Added in version 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).

Added in version 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.

Added in version 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().

Added in version 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.