STRFMON(3)

NOME
strfmon - converte valor monetário para uma seqüencia

SINÓPSE
#include <monetary.h>

ssize_t strfmon(char *s, size_t max, const char *formato,
...);

DESCRIÇÃO
A função strfmon() formata as quantias especificadas de acordo com a especificação de formato formato e coloca o resultado no vetor de caractere s de tamanho max.

Caracteres comuns em format são copiados para s sem conversão. Especificadores de conversão são introduzidos por um caractere `%'. Imediatamente após ele pode haver zero ou mais dos seguintes sinalizadores:

=f  O caractere de um byte f é usado como caractere de preenchimento numérico (a ser usado com uma precisão à esquerda, veja abaixo). Quando não especificado, o caractere de espaço é utilizado.

^   Não usar quaisquer caracteres de agrupamento que possam estar definidos para a localidade atual. Por padrão, agrupamento está habilitado.

( ou +
    O sinalizador ( indica que quantias negativas devem estar entre parênteses. O sinalizador + indica que sinais devem ser manipulados da maneira padrão, isto é, quantias são precedidas pelo indicador de sinal da localidade, por exemplo, nada para positivo, '-' para negativo.

!   Omite o símbolo da moeda.

-   Justifica à esquerda todos os campos. O padrão é justificação à direita.

Em seguida, deve haver um campo de largura: uma seqüencia de dígitos decimais especificando uma largura mínima de campo em bytes. O padrão é 0. Um resultado menor que esta largura é preenchido com espaços (à esquerda, a menos que o sinalizador de justificação à esquerda tenha sido dado).

Em seguida, deve haver uma precisão à esquerda da forma '#' seguido por uma seqüencia de dígitos decimais. Se o número de dígitos à esquerda do caractere de decimais ('ponto fracionário') for menor que isto, a representação é preenchida à esquerda com o caractere de preenchimento numérico. Caracteres de agrupamento não são contados na largura deste campo.

Em seguida, deve haver uma precisão à direita da forma '.' seguido por uma seqüencia de dígitos decimais. A quantia sendo formatada é arredondada para o número especificado de dígitos antes de ser formatada. O padrão é especificado nos itens frac_digits e int_frac_digits das configurações regionais atuais. Se a precisão à direita for 0, nenhum caractere de decimais é exibido. (O caractere de decimais aqui é determinado por LC_MONETARY, e pode diferir daquele especificado por LC_NUMERIC.)

Finalmente, a especificação de conversão deve acabar com um caractere de conversão. Os três caracteres de conversão são

%   (Neste caso a especificação completa deve ser exatamente '%%'.) Coloca um caractere '%' na seqüencia de resultado.

i   Um argumento do tipo double é convertido usando o formato internacional de moeda das configurações regionais atuais.

n   Um argumento do tipo double é convertido usando o formato nacional de moeda das configurações regionais atuais.

VALORES RETORNADOS
A função strfmon() retorna o número de caracteres colocados no vetor s, não incluindo o caractere terminador NULO, desde que a seqüencia, incluindo o terminador NULO, caiba no espaço. Caso contrário, ela define errno para E2BIG, retorna -1, e o conteúdo do vetor é indefinido.

EXEMPLO
A chamada
    strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]",
            1234.567, 1234.567);
produz como saída
    [ fl **1234,57] [ NLG **1 234,57]
na configuração regional holandesa (com fl para 'florijnen' e NLG para 'Netherlands Guilders'). O caractere de agrupamento é feio porque ele toma tanto espaço quanto um dígito, quando não deveria tomar mais que a metade disso, e sem dúvida causará confusão. Surpreendentemente, o 'fl' é precedido e seguido por um espaço, e 'NLG' é precedido por um e seguido por dois espaços. Isso pode ser um bug nos arquivos de configuração regional. As configurações italiana, australiana, suíça e portuguesa produzem
    [ L. **1235] [ ITL **1.235]
    [ $**1234.57] [ AUD **1,234.57]
    [Fr. **1234,57] [CHF **1.234,57]
    [ **1234$57Esc] [ **1.234$57PTE ]

VEJA TAMBÉM
setlocale(3), sprintf(3), locale(7).

TRADUZIDO POR LDP-BR em 15/03/2001.

  Tradução:
Marcelo M. de Abreu <mmabreu@terra.com.br>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>