_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l

  • Artigo

Grave dados formatados em uma cadeia de caracteres com a capacidade de especificar a ordem em que os parâmetros são usados na cadeia de caracteres de formato.

Sintaxe

int _sprintf_p(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format [,
   argument_list]
);
int _sprintf_p_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   _locale_t locale [,
   argument_list]
);
int _swprintf_p(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format [,
   argument_list]
);
int _swprintf_p_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   _locale_t locale [,
   argument_list]
);

Parâmetros

buffer
Local de armazenamento para a saída

sizeOfBuffer
O número máximo de caracteres a ser armazenado.

format
Cadeia de caracteres de controle de formato.

argument_list
Argumentos opcionais para a cadeia de caracteres de formato.

locale
A localidade a ser usada.

Para obter mais informações, consulte Sintaxe de especificação de formato.

Retornar valor

O número de caracteres gravados ou -1 se ocorreu um erro.

Comentários

A função _sprintf_p formata e armazena uma série de caracteres e valores em buffer. Cada argumento na argument_list (se houver) é convertido e gerado de acordo com a especificação de formato correspondente em format. O argumento format usa a sintaxe de especificação de formato para as funções printf e wprintf. Um caractere nulo é acrescentado após o último caractere escrito. Se ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido. A diferença entre _sprintf_p e sprintf_s é que _sprintf_p dá suporte a parâmetros posicionais, o que permite especificar a ordem em que os argumentos são usados na cadeia de formato. Para obter mais informações, confira Parâmetros posicionais printf_p.

_swprintf_p é uma versão de caractere largo de _sprintf_p; os argumentos de ponteiro para _swprintf_p são cadeias de caracteres largos. A detecção de erros de codificação em pode diferir da detecção em _swprintf_p_sprintf_p. _swprintf_p e fwprintf_p comportam-se de modo idêntico, exceto pelo fato de que _swprintf_p grava a saída em uma cadeia de caracteres em vez de um destino do tipo FILE, além de que _swprintf_p requer que o parâmetro count especifique o número máximo de caracteres a serem gravados. As versões dessas funções com o sufixo _l são idênticas, com a exceção de usarem o parâmetro de localidade passado, em vez da localidade do thread atual.

_sprintf_p retorna o número de bytes armazenados em buffer, sem contar o caractere nulo de terminação. _swprintf_p retorna o número de caracteres largos armazenados em buffer, sem contar o caractere largo nulo de terminação. Se buffer ou for um ponteiro nulo, ou format se a cadeia de caracteres de formato contiver caracteres de formatação inválidos, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão -1 e definirão errno como EINVAL.

Importante

Começando pelo Windows 10 versão 2004 (build 19041), a família de funções printf imprime números de ponto flutuante exatamente representáveis de acordo com as regras do IEEE 754 para arredondamento. Em versões anteriores do Windows, números de ponto flutuante que pudessem ser representados com exatidão e que terminassem em '5' eram sempre arredondados para cima. O IEEE 754 afirma que eles precisam arredondar para o dígito par mais próximo (também conhecido como "arredondamento bancário"). Por exemplo, ambos printf("%1.0f", 1.5) e printf("%1.0f", 2.5) devem ser arredondados para 2. Anteriormente, 1,5 seria arredondado para 2 e 2,5 para 3. Essa alteração afeta apenas números que possam ser representados com exatidão. Por exemplo, 2,35 (que, quando representado na memória, está mais próximo de 2,35000000000000008) continua arredondando para 2,4. O arredondamento feito por essas funções agora também respeita o modo de arredondamento de ponto flutuante definido por fesetround. Anteriormente, o arredondamento sempre escolhia o comportamento FE_TONEAREST. Essa alteração afeta apenas os programas criados usando o Visual Studio 2019 versão 16.2 e posteriores. Para usar o comportamento de arredondamento de ponto flutuante herdado, vincule-o a 'legacy_stdio_float_rounding.obj'.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H _UNICODE e _MBCS não definidos _MBCS definido _UNICODE definido
_stprintf_p _sprintf_p _sprintf_p _swprintf_p
_stprintf_p_l _sprintf_p_l _sprintf_p_l _swprintf_p_l

Requisitos

Rotina Cabeçalho necessário
_sprintf_p, _sprintf_p_l <stdio.h>
_swprintf_p, _swprintf_p_l <stdio.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo: Usar _sprintf_p para formatar dados

// crt_sprintf_p.c
// This program uses _sprintf_p to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
    char     buffer[200],
            s[] = "computer", c = 'l';
    int      i = 35,
            j;
    float    fp = 1.7320534f;

    // Format and print various data:
    j  = _sprintf_p( buffer, 200,
                     "   String:    %s\n", s );
    j += _sprintf_p( buffer + j, 200 - j,
                     "   Character: %c\n", c );
    j += _sprintf_p( buffer + j, 200 - j,
                     "   Integer:   %d\n", i );
    j += _sprintf_p( buffer + j, 200 - j,
                     "   Real:      %f\n", fp );

    printf( "Output:\n%s\ncharacter count = %d\n",
            buffer, j );
}

Output:
   String:    computer
   Character: l
   Integer:   35
   Real:      1.732053

character count = 79

Exemplo: Tratamento de código de erro

// crt_swprintf_p.c
// This is the wide character example which
// also demonstrates _swprintf_p returning
// error code.
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    wchar_t buffer[BUFFER_SIZE];
    int     len;

    len = _swprintf_p(buffer, BUFFER_SIZE, L"%2$s %1$d",
                      0, L" marbles in your head.");
    _printf_p( "Wrote %d characters\n", len );

    // _swprintf_p fails because string contains WEOF (\xffff)
    len = _swprintf_p(buffer, BUFFER_SIZE, L"%s",
                      L"Hello\xffff world" );
    _printf_p( "Wrote %d characters\n", len );
}

Wrote 24 characters
Wrote -1 characters

Confira também

E/S de fluxo
_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l
_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l
Funções vprintf
printf_p Parâmetros posicionais