subrotinas fwprintf, wprintf, swprintf

Propósito

Imprimir saída de caráter amplo formatado.

Biblioteca

Biblioteca Padrão (libc.a)

Sintaxe

#include <stdio.h>
#include <wchar.h>

int fwprintf ( FILE * stream, const wchar_t * format, . . .)
int wprintf (const wchar_t * format, . .)
int swprintf (wchar_t *s, size_t n, const wchar_t * format, . . .)

Descrição

A função fwprintf coloca saída no fluxo de saída nomeado. A função wprintf coloca a saída no fluxo de saída padrão stdout. A função swprintf coloca saída seguida do caractere de largura nula em caracteres de largura consecutivos iniciando em * s; não mais do que n wide-caracteres são escritos, incluindo um caractere de largura nula de terminação, que é sempre adicionado (a menos que n seja zero).

Cada uma dessas funções se converte, formata e imprime seus argumentos sob controle da cadeia de caracteres de todo o formato . O formato é composto por zero ou mais diretivas: caracteres amplos ordinários, que são simplesmente copiadas para o fluxo de saída e especificações de conversão , cada uma das quais resulta na busca de zero ou mais argumentos. Os resultados são indefinidos se houver argumentos insuficientes para o formato. Se o formato estiver esgotado enquanto os argumentos permanecem, os argumentos em excesso são avaliados mas são ignorados de outra forma.

As Conversões EX podem ser aplicadas no argumento nês após o formato na lista de argumentos, em vez de para o próximo argumento não utilizado. Neste caso, o wide-character% (ver abaixo) é substituído pela sequência %n$, em que n é um inteiro decimal no intervalo [1, {NL_ARGMAX}], dando a posição do argumento na lista de argumentos. Este recurso prevê a definição de strings de caracteres de formato amplo que selecionam argumentos em uma ordem apropriada para linguagens específicas (veja a seção EXEMPLOS).

Em sequências de caracteres de formato amplo contendo a forma %n$ de especificações de conversão, argumentos numerados na lista de argumentos podem ser referenciados a partir da cadeia de caracteres de caracteres de formato amplo quantas vezes for necessário.

Em formato de strings de caracteres de grande formato contendo a forma% de especificações de conversão, cada argumento na lista de argumentos é usado exatamente uma vez.

Todas as formas das funções fwprintf permitem a inserção de um caractere de radix dependente de linguagem na cadeia de saída, saída como um valor de amplo caráter. O caractere radix é definido no locale do programa (category LC_NUMÉRICO). No locale POSIX , ou em um locale onde o caractere radix não é definido, o caractere radix padronizado para um período (.).

EX Cada especificação de conversão é introduzida pela% de amplo caráter ou pela sequência de caracteres de grande caráter %n$, após a qual aparecem os seguintes em sequência:

• Zero ou mais bandeiras (em qualquer ordem), que modificam o significado da especificação de conversão.
• Um mínimo opcional largura do campo. Se o valor convertido tiver menos caracteres amplos que a largura do campo, ele será preenchido com espaços por padrão à esquerda; ele será preenchido à direita, se a sinalização de reajuste de esquerda (-), descrita abaixo, for dada à largura do campo. A largura de campo assume a forma de um asterisco (*), descrito abaixo, ou um inteiro decimal.
• Um precisão opcional que dá o número mínimo de dígitos para aparecer para as conversões d, i, o, u, x e X ; o número de dígitos a aparecer após o caractere radix para as conversões de e, E e f; o número máximo de dígitos significativos para as conversões g e G; ou o número máximo de caracteres largos a serem impressos a partir de uma string em s conversões. A precisão toma a forma de um período (.) seguido de um asterisco (*), descrito a seguir, ou uma sequência de algarismos decimal opcional, em que uma cadeia de algarismos nulos é tratada como 0. Se uma precisão aparece com qualquer outro caráter amplo de conversão, o comportamento é indefinido.
• Um l opcional (lowercase L), L, h, H, D ou DD especifica uma das seguintes conversões:
  • Um l opcional especificando que um seguinte caractere de conversão c se aplica a um argumento wint_t .
  • Um l opcional especificando que um seguinte caractere de conversão s se aplica a um argumento wchar_t .
  • Um l opcional especificando que um seguinte caractere d, eu, o, u, x ou X de conversão de caracteres aplica-se a um argumento tipo longa int ou longo int unsigned .
  • Um l opcional especificando que um seguinte caractere de conversão n se aplica a um ponteiro a um argumento tipo longa int .
  • Um L opcional especificando que um seguinte caractere de conversão e, E, f, g ou G , aplica-se a um argumento tipo longo duplo .
  • Um h opcional especificando que um caractere de conversão de d, eu, o, u, x ou X , aplica-se a um argumento tipo curta int ou tipo curta int unsigned (o argumento que será promovido de acordo com as promoções integrais, e seu valor será convertido para o tipo curta int ou curta int unsigned antes da impressão).
  • Um h opcional especificando que um seguinte caractere de conversão n se aplica a um ponteiro a um argumento tipo curta int .
  • Um H opcional especificando que um seguinte caractere e, E, f, gou G de conversão de caracteres aplica-se a um parâmetro _Decimal32 .
  • Um D opcional especificando que um seguinte caractere e, E, f, gou G de conversão de caracteres aplica-se a um parâmetro _Decimal64 .
  • Um DD opcional especificando que um seguinte caractere e, E, f, gou G de conversão de caracteres aplica-se a um parâmetro _Decimal128 .
  Se um l, L , h, H, Dou DD aparecer com qualquer outro caractere de ampla conversão, o comportamento será indefinido.
• Um conversão de caráter amplo que indica o tipo de conversão a ser aplicada.

Uma largura de campo, ou precisão, ou ambas, pode ser indicada por um asterisco (*). Nesse caso um argumento do tipo int fornece a largura de campo ou precisão. Argumentos especificando largura de campo, ou precisão, ou ambos devem aparecer nessa ordem antes do argumento, se houver, para ser convertido. Uma largura de campo negativa é tida como uma-bandeira seguida de uma largura de campo positiva. Uma precisão negativa é tomada como se EX a precisão fosse omitida. Em format wide-character strings contendo a forma %n$ de uma especificação de conversão, uma largura de campo ou precisão pode ser indicada pela sequência * m$, em que m é um inteiro decimal na faixa [1, {NL_ARGMAX}] dando a posição na lista de argumentos (após o argumento format) de um argumento inteiro contendo a largura de campo ou precisão, por exemplo:

 wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);

O formato pode conter especificações de argumento numeradas (ou seja, %n$ e * m$), ou especificações de argumento não numeradas (ou seja,% e *), mas normalmente não ambas. A única exceção a isso é que%% pode ser misturado com o formulário %n$ . Os resultados de mixagem de especificações de argumentos numerados e não numerados em uma sequência de caracteres de grande alcance de formato são indefinidos. Quando especificações de argumento numeradas são usadas, especificar o argumento Nth requer que todos os argumentos líderes, da primeira para a (N-1) th, sejam especificados na string de formato de caracteres.

A bandeira wide-caracteres e seus significados são:

Os caracteres amplos de conversão e seus significados são:

Se uma especificação de conversão não corresponder a uma das formas acima, o comportamento será indefinido.

Em nenhum caso uma largura de campo inexistente ou pequena causa truncamento de um campo; se o resultado de uma conversão for mais largo do que a largura do campo, o campo é simplesmente expandido para conter o resultado da conversão. Os caracteres gerados por fwprintf e wprintf são impressos como se fputwc tivesse sido chamado.

Os campos st_ctime e st_mtime do arquivo serão marcados para atualização entre a chamada para uma execução bem-sucedida de fwprintf ou wprintf e a próxima conclusão bem-sucedida de uma chamada para fflush ou ffechar no mesmo fluxo ou uma chamada para sair ou abortar.

Valores De Retorno

Após a conclusão bem-sucedida, essas funções retornam o número de caracteres amplos transmitidos excluindo-se a terminação de wide-character nula no caso de swprintf ou um valor negativo se um erro de saída foi encontrado.

Códigos De Erro

Para as condições sob as quais fwprintf e wprintf falharão e podem falhar, consulte o fputwc. Além disso, todas as formas de fwprintf podem falhar se:

O swprintf falhará se:

Exemplos

Para imprimir o formato de data e hora independente do idioma, poderá ser utilizada a seguinte declaração:

 wprintf (format, weekday, month, day, hour, min);

Para o uso americano, o formato poderia ser um ponteiro para a cadeia de caracteres de grande caráter:

 L"%s, %s %d, %d:%.2d\n"

produzindo a mensagem:

 Sunday, July 3, 10:02

que para o uso alemão, o formato poderia ser um ponteiro para a cadeia de caracteres ampla:

L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"

produzindo a mensagem:

 Sonntag, 3. July, 10:02