Formata um número como uma string de moeda

Descrição

money_format(string $format, float $number): string

money_format() retorna uma versão formatada de um number. 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.

Parâmetros

format

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 (único byte) 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 símbolo 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 %.

number

O número para ser formatado.

Valor Retornado

Retorna a string formatada. Os caracteres antes e depois da string de formatação serão retornados sem modificação. O parâmetro number com dígitos inválidos causa o retorno de null e o lançamento de um E_WARNING.

Registro de Alterações

Versão	Descrição
7.4.0	Esta função foi descontinuada. Utilize NumberFormatter::formatCurrency().

Exemplos

Example #1 Exemplo da money_format()

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";
// Eu 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, without the 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";
// Eu 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)

?>

Notas

Note:
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.

Note:
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.

Veja Também

setlocale() - Define informação de localidade
sscanf() - Interpreta a entrada de uma string de acordo com um formato
sprintf() - Retona uma string formatada
printf() - Envia uma string formatada para a saída
number_format() - Formata um número com milhares agrupados