money_format

(PHP 4 >= 4.3.0, PHP 5)

money_format — Formata um número como uma string de moeda

Descrição

string money_format ( string $formato , float $numero )

money_format() retorna uma versão formatada de um numero . Esta função engloba a biblioteca de função do C strfmon(), com a diferença que esta implementação converte apenas um número por vez.

Nota: A função money_format() é apenas definida se o sistema tem capacidades de strfmon. Por exemplo, o Windows não tem, então money_format() está indefinida o Windows.

A especificação do formato consistem da seguinte sequência:

a % character
flags opcionais
largura de campo opcional
precisão da esquerda opcional
precisão da direita opcional
conversão de caractere requerida

Flags

Uma ou mais, das flags opcionais abaixo podem ser usadas:

=f: O caracter = seguido por um caractere (byte simples) f para ser usado como o caracter númerico de preenchimento. O caractere de preenchimento padrão é o espaço.
^: Desabilite o uso de agrupamento de caractere (como definido pela localidade atual).
+ ou (: Especifique o estilo de formatação para números positivos e negativos. Se + é usado, o equivalente da localidade para + e - será usado. Se ( é usado, quantias negativas são fechadas em parêntesis. se nenhuma especificação é dada, o padrão será +.
!: Suprima o simbolo atual da string de saída.
-: Se presente, isso fará todos os campos esquerda-justificados (arrumados para a direita), em oposição ao padrão que é para campos serem direita-justificados (arrumados para a esquerda).

Largura de campo

w: Uma string de dígito decimal especificando uma largura de campo mínima. O campo será direita-justificado a menos que o flag - seja usado. Valor padrão é 0 (zero) por definição.

Precisão de esquerdan

#n

O número máximo de dígitos (n) esperado para a esquerda do caracatere decimal(ex. ponto decimal). Isso é usado normalmente para manter a saída formatada alinhada nas mesmas colunas, usando o caractere de preenchimento se o número de dígitos é menor do que n. Se o número de dígitos atual é maior do que n, então esta especificação é ignorada.

Se agrupamento foi suprimido usando a flag ^, separatores de agrupamento serão inseridos antes dos caracteres de preenchimento (se algum) são adicionados, mesmo se o caractere de preenchimento é um dígito.

Para garantir alinhamento, quaisquer caracteres aparecendo, antes ou depois do número em saída formatada, como moeda ou simbolos de sinal, são arrumado conforme necessário, com caracteres de espaço para fazer seus formatos positivos e negativos num comprimento igual.

Precisão de direita

.p: Um período seguido por um número de dígitos (p) depois do caractere decimal. Se o valor de p é 0 (zero), o caractere decimal e os digitos à sua direita serão omitidos. Se nenhuma precisão de direita é incluida, o padrão será ditado pela localidade atual em uso. A quantia sendo formatada é arredondada para o número de dígitos especificados a priori para ser formatado.

Caracteres de conversão

i: O número é formatado de acordo com o formato de moeda internacional da localidade (ex para a localidade de EUA: USD 1,234.56).
n: O número é formatado de acordo com o formato de moeda nacional da localidade (ex: para a localidade de_DE: DM1.234,56).
%: Retorna o caractere %.

Nota: A categoria LC_MONETARY de configurações de localidade, afeta o comportamento desta função. Utilize setlocale() para definir a localidade padrão apropriadamente antes de usar esta função.
Os caracteres antes e depois da string de formatação serão retornados sem modificação.

Example#1 money_format() Exemplo

Nós usaremos localidades diferentes e especificações de formatos e localidades para ilustrar o uso desta função.


<?php

$number = 1234.56;

// let's print the international format for the en_US locale
setlocale(LC_MONETARY, 'en_US');
echo money_format('%i', $number) . "\n";  
// USD 1,234.56

// Italian national format with 2 decimals`
setlocale(LC_MONETARY, 'it_IT');
echo money_format('%.2n', $number) . "\n";
// L. 1.234,56

// Using a negative number
$number = -1234.5672;

// US national format, using () for negative numbers
// and 10 digits for left precision
setlocale(LC_MONETARY, 'en_US');
echo money_format('%(#10n', $number) . "\n";
// ($        1,234.57)

// Similar format as above, adding the use of 2 digits of right 
// precision and '*' as a fill character
echo money_format('%=*(#10.2n', $number) . "\n";
// ($********1,234.57)
    
// Let's justify to the left, with 14 positions of width, 8 digits of
// left precision, 2 of right precision, withouth grouping character
// and using the international format for the de_DE locale.
setlocale(LC_MONETARY, 'de_DE');
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// DEM 1234,56****

// Let's add some blurb before and after the conversion specification
setlocale(LC_MONETARY, 'en_GB');
$fmt = 'The final value is %i (after a 10%% discount)';
echo money_format($fmt, 1234.56) . "\n";
// The final value is  GBP 1,234.56 (after a 10% discount)

?>

Veja também: setlocale(), number_format(),sprintf(), printf() e sscanf().