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, ...)¶ 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)¶ 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
e 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:
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 emstr[rv]
).Quando
rv >= size
, a conversão de saída foi truncada e um buffer comrv + 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
emdouble
, levantando uma exceção Python em caso de falha. O conjunto de strings aceitas corresponde ao conjunto de strings aceito pelo construtorfloat()
do Python, exceto ques
não deve ter espaços em branco à esquerda ou à direita. A conversão é independente da localidade atual.Se
endptr
forNULL
, converte a string inteira. LevantaValueError
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 seoverflow_exception
forNULL
retornaPy_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; 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
.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 derepr()
.flags pode ser zero ou mais de valores
Py_DTSF_SIGN
,Py_DTSF_ADD_DOT_0
ouPy_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'#'
dePyOS_snprintf()
para detalhes.
Se type não for
NULL
, então o valor para o qual ele aponta será definido como um dosPy_DTST_FINITE
,Py_DTST_INFINITE
ouPy_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 chamandoPyMem_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.