A classe NumberFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Introdução

Programas armazenam e operam números usando uma representação binária que não depende da localidade. Ao apresentar ou imprimir um número, ele é convertido para uma string específica para a localidade. Por exemplo, o número 12345.67 é "12,345.67" nos Estados Unidos, "12 345,67" na França e "12.345,67" na Alemanha e no Brasil.

Ao invocar os métodos fornecidos pela classe NumberFormatter, pode-se formatar números, moedas, e percentagens de acordo com o especificado ou com a localidade padrão. NumberFormatter é sensível à localidade, portanto é necessário criar um novo objeto NumberFormatter para cada localidade. Métodos NumberFormatter formatam números com tipos primitivos, como 'double' e mostram o número como uma string específica para a localidade

Para moedas, pode-se usar o tipo de formato de moeda para criar um formatador que retorne uma string com o número formatado e com o sinal apropriado para a moeda. Obviamente, a classe NumberFormatter não tem ciência de taxas de câmbio, portanto, a saída é a mesma independente da moeda especificada. Isto significa que o mesmo número tem diferentes valores monteários dependendo da moeda da localidade. Se o número for 9988776.65, os resultados serão:

9 988 776,65 € na França
9.988.776,65 € na Alemanha
$9,988,776.65 nos Estados Unidos

Para formatar percentagens, deve-se criar um formatador específico da localidade com o tipo de formato de percentual. Com este formatados, uma fração decimal como 0.75 é mostrada como 75%.

Para formatações mais complexas, como números por extenso, os formatadores de número baseados em regras são utilizados.

Resumo da classe

class NumberFormatter {

/* Constantes */

public const int PATTERN_DECIMAL;

public const int DECIMAL;

public const int DECIMAL_COMPACT_SHORT;

public const int DECIMAL_COMPACT_LONG;

public const int CURRENCY;

public const int PERCENT;

public const int SCIENTIFIC;

public const int SPELLOUT;

public const int ORDINAL;

public const int DURATION;

public const int PATTERN_RULEBASED;

public const int IGNORE;

public const int CURRENCY_ISO;

public const int CURRENCY_PLURAL;

public const int CURRENCY_ACCOUNTING;

public const int CASH_CURRENCY;

public const int CURRENCY_STANDARD;

public const int DEFAULT_STYLE;

public const int ROUND_CEILING;

public const int ROUND_FLOOR;

public const int ROUND_DOWN;

public const int ROUND_UP;

public const int ROUND_TOWARD_ZERO;

public const int ROUND_AWAY_FROM_ZERO;

public const int ROUND_HALFEVEN;

public const int ROUND_HALFODD;

public const int ROUND_HALFDOWN;

public const int ROUND_HALFUP;

public const int PAD_BEFORE_PREFIX;

public const int PAD_AFTER_PREFIX;

public const int PAD_BEFORE_SUFFIX;

public const int PAD_AFTER_SUFFIX;

public const int PARSE_INT_ONLY;

public const int GROUPING_USED;

public const int DECIMAL_ALWAYS_SHOWN;

public const int MAX_INTEGER_DIGITS;

public const int MIN_INTEGER_DIGITS;

public const int INTEGER_DIGITS;

public const int MAX_FRACTION_DIGITS;

public const int MIN_FRACTION_DIGITS;

public const int FRACTION_DIGITS;

public const int MULTIPLIER;

public const int GROUPING_SIZE;

public const int ROUNDING_MODE;

public const int ROUNDING_INCREMENT;

public const int FORMAT_WIDTH;

public const int PADDING_POSITION;

public const int SECONDARY_GROUPING_SIZE;

public const int SIGNIFICANT_DIGITS_USED;

public const int MIN_SIGNIFICANT_DIGITS;

public const int MAX_SIGNIFICANT_DIGITS;

public const int LENIENT_PARSE;

public const int POSITIVE_PREFIX;

public const int POSITIVE_SUFFIX;

public const int NEGATIVE_PREFIX;

public const int NEGATIVE_SUFFIX;

public const int PADDING_CHARACTER;

public const int CURRENCY_CODE;

public const int DEFAULT_RULESET;

public const int PUBLIC_RULESETS;

public const int DECIMAL_SEPARATOR_SYMBOL;

public const int GROUPING_SEPARATOR_SYMBOL;

public const int PATTERN_SEPARATOR_SYMBOL;

public const int PERCENT_SYMBOL;

public const int ZERO_DIGIT_SYMBOL;

public const int DIGIT_SYMBOL;

public const int MINUS_SIGN_SYMBOL;

public const int PLUS_SIGN_SYMBOL;

public const int CURRENCY_SYMBOL;

public const int INTL_CURRENCY_SYMBOL;

public const int MONETARY_SEPARATOR_SYMBOL;

public const int EXPONENTIAL_SYMBOL;

public const int PERMILL_SYMBOL;

public const int PAD_ESCAPE_SYMBOL;

public const int INFINITY_SYMBOL;

public const int NAN_SYMBOL;

public const int SIGNIFICANT_DIGIT_SYMBOL;

public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;

public const int TYPE_DEFAULT;

public const int TYPE_INT32;

public const int TYPE_INT64;

public const int TYPE_DOUBLE;

public const int TYPE_CURRENCY;

/* Métodos */

public __construct(string $locale, int $style, ?string $pattern = null)

public static create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter

public format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false

public formatCurrency(float $amount, string $currency): string|false

public getAttribute(int $attribute): int|float|false

public getErrorCode(): int

public getErrorMessage(): string

public getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false

public getPattern(): string|false

public getSymbol(int $symbol): string|false

public getTextAttribute(int $attribute): string|false

public parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|float|false

public parseCurrency(string $string, string &$currency, int &$offset = null): float|false

public setAttribute(int $attribute, int|float $value): bool

public setPattern(string $pattern): bool

public setSymbol(int $symbol, string $value): bool

public setTextAttribute(int $attribute, string $value): bool

}

Constantes predefinidas

Tipos de Formato

Estes estilos são usados pela função numfmt_create() para definir o tipo do formatador.

NumberFormatter::PATTERN_DECIMAL int: Formato decimal definido por modelo
NumberFormatter::DECIMAL int: Formato decimal
NumberFormatter::DECIMAL_COMPACT_SHORT int: Formato decimal expresso em notação compacta (forma curta), por exemplo, "23K", "45B". Disponível a partir do PHP 8.5.0 e ICU 56.
NumberFormatter::DECIMAL_COMPACT_LONG int: Formato decimal expresso em notação compacta (forma longa), por exemplo, "23 thousand", "45 billion". Disponível a partir do PHP 8.5.0 e ICU 56.
NumberFormatter::CURRENCY int: Formato de moeda
NumberFormatter::CURRENCY_ISO int: Formato ISO de moeda (ex.: "USD1.00"). Disponível a partir do PHP 8.5.0.
NumberFormatter::CURRENCY_PLURAL int: Formato pluralizado de moeda (ex.: "1.00 US dollar" e "3.00 US dollars"). Disponível a partir do PHP 8.5.0.
NumberFormatter::CASH_CURRENCY int: Símbolo da moeda em uso de DINHEIRO, por exemplo, "NT$3" em vez de "NT$3.23". Disponível a partir do PHP 8.5.0 e ICU 54.
NumberFormatter::CURRENCY_STANDARD int: Símbolo de moeda, por exemplo, "$1.00", usando estilo não contábil para valores negativos (por exemplo, sinal de menos). Disponível a partir do PHP 8.5.0 e ICU 56.
NumberFormatter::PERCENT int: Formato de percentual
NumberFormatter::SCIENTIFIC int: Formato científico
NumberFormatter::SPELLOUT int: Formato baseado em regras ortográficas
NumberFormatter::ORDINAL int: Formato baseado em regras ordinais
NumberFormatter::DURATION int: Formato baseado em regras de duração
NumberFormatter::PATTERN_RULEBASED int: Formato baseado em regras definido por modelo
NumberFormatter::CURRENCY_ACCOUNTING int: Formato de moeda para contabilidade, ex.: ($3.00) para quantidade negativa de moeda ao invés de -$3.00. Disponível a partir do PHP 7.4.1 e ICU 53.
NumberFormatter::DEFAULT_STYLE int: Formato padrão para a localidade
NumberFormatter::IGNORE int: Apelido para PATTERN_DECIMAL

Especificadores de Formatos de Números

Estas constantes definem como os números são analisados ou formatados. Eles devem ser usados como argumentos para as funções numfmt_format() e numfmt_parse().

NumberFormatter::TYPE_DEFAULT int: Deriva o tipo a partir do tipo da variável
NumberFormatter::TYPE_INT32 int: Formata/analisa como um inteiro de 32 bits
NumberFormatter::TYPE_INT64 int: Formata/analisa como um inteiro de 64 bits
NumberFormatter::TYPE_DOUBLE int: Formata/analisa como um valor de ponto flutuante
NumberFormatter::TYPE_CURRENCY int: Formata/analisa como um valor de moeda. Descontinuado a partir do PHP 8.3.0

Atributos de Formatos de Números

Atributo de formato de número usado pelas funções numfmt_get_attribute() e numfmt_set_attribute().

NumberFormatter::PARSE_INT_ONLY int: Analisa inteiros somente.
NumberFormatter::GROUPING_USED int: Usa separador de agrupamento.
NumberFormatter::DECIMAL_ALWAYS_SHOWN int: Sempre mostra o separador de decimais.
NumberFormatter::MAX_INTEGER_DIGITS int: Máximo de dígitos inteiros.
NumberFormatter::MIN_INTEGER_DIGITS int: Mínimo de dígitos inteiros.
NumberFormatter::INTEGER_DIGITS int: Dígitos inteiros.
NumberFormatter::MAX_FRACTION_DIGITS int: Máximo de dígitos decimais.
NumberFormatter::MIN_FRACTION_DIGITS int: Mínimo de dígitos decimais.
NumberFormatter::FRACTION_DIGITS int: Dígitos decimais.
NumberFormatter::MULTIPLIER int: Multiplicador.
NumberFormatter::GROUPING_SIZE int: Tamanho do agrupamento.
NumberFormatter::ROUNDING_MODE int: Modo de arredondamento.
NumberFormatter::ROUNDING_INCREMENT int: Incremento de arredondamento.
NumberFormatter::FORMAT_WIDTH int: A largura para a qual a saída de format() será preenchida.
NumberFormatter::PADDING_POSITION int: A posição na qual o preenchimento acontecerá. Consulte as constantes de posição de preenchimento para possíveis valores de argumentos.
NumberFormatter::SECONDARY_GROUPING_SIZE int: Tamanho de agrupamento secundário.
NumberFormatter::SIGNIFICANT_DIGITS_USED int: Usa dígitos significativos.
NumberFormatter::MIN_SIGNIFICANT_DIGITS int: Mínimo de dígitos significativos.
NumberFormatter::MAX_SIGNIFICANT_DIGITS int: Máximo de dígitos significativos.
NumberFormatter::LENIENT_PARSE int: Modo de análise brando usado por formatos baseados em regras.

Atributos de Texto de Formatos de Números

Atributo de texto de formato numérico usado por numfmt_get_text_attribute() e numfmt_set_text_attribute().

NumberFormatter::POSITIVE_PREFIX int: Prefixo positivo.
NumberFormatter::POSITIVE_SUFFIX int: Sufixo positivo.
NumberFormatter::NEGATIVE_PREFIX int: Prefixo negativo.
NumberFormatter::NEGATIVE_SUFFIX int: Sufixo negativo.
NumberFormatter::PADDING_CHARACTER int: O caractere usado para preencher a largura do formato.
NumberFormatter::CURRENCY_CODE int: O código de moeda ISO.
NumberFormatter::DEFAULT_RULESET int: O conjunto de regras padrão. Isso está disponível apenas com formatadores baseados em regras.
NumberFormatter::PUBLIC_RULESETS int: Os conjuntos de regras públicas. Isso está disponível apenas com formatadores baseados em regras. Este é um atributo somente leitura. Os conjuntos de regras públicos são retornados como uma única string, com cada nome de conjunto de regras delimitado por ';' (ponto e vírgula).

Especificadores de Formatos de Símbolos

Símbolos de formato de número usados por numfmt_get_symbol() e numfmt_set_symbol().

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL int: O separador de decimais.
NumberFormatter::GROUPING_SEPARATOR_SYMBOL int: O separador de agrupamento.
NumberFormatter::PATTERN_SEPARATOR_SYMBOL int: O separador de padrão.
NumberFormatter::PERCENT_SYMBOL int: O sinal de percentagem.
NumberFormatter::ZERO_DIGIT_SYMBOL int: Zero.
NumberFormatter::DIGIT_SYMBOL int: Caractere representando um dígito no padrão.
NumberFormatter::MINUS_SIGN_SYMBOL int: O sinal de menos.
NumberFormatter::PLUS_SIGN_SYMBOL int: O sinal de mais.
NumberFormatter::CURRENCY_SYMBOL int: O símbolo da moeda.
NumberFormatter::INTL_CURRENCY_SYMBOL int: O símbolo internacional da moeda.
NumberFormatter::MONETARY_SEPARATOR_SYMBOL int: O separador monetário.
NumberFormatter::EXPONENTIAL_SYMBOL int: O símbolo exponencial.
NumberFormatter::PERMILL_SYMBOL int: O símbolo de permilagem.
NumberFormatter::PAD_ESCAPE_SYMBOL int: Caractere de preenchimento de escape.
NumberFormatter::INFINITY_SYMBOL int: Símbolo de infinito.
NumberFormatter::NAN_SYMBOL int: Símbolo representando que o valor não é um número.
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL int: Símbolo de dígito significativo.
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL int: O separador de agrupamento monetário.

Modos de Arredondamento

Valores de modo de arredondamento usados por numfmt_get_attribute() e numfmt_set_attribute() com o atributo NumberFormatter::ROUNDING_MODE.

NumberFormatter::ROUND_AWAY_FROM_ZERO: Sinônimo de NumberFormatter::ROUND_UP.
NumberFormatter::ROUND_CEILING int: Modo de arredondamento para arredondar em direção ao infinito positivo.
NumberFormatter::ROUND_DOWN int: Modo de arredondamento para arredondar para zero.
NumberFormatter::ROUND_FLOOR int: Modo de arredondamento para arredondar em direção ao infinito negativo.
NumberFormatter::ROUND_HALFDOWN int: Modo de arredondamento para arredondar para o "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes, caso em que arredonda para baixo.
NumberFormatter::ROUND_HALFEVEN int: Modo de arredondamento para arredondar em direção ao "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes; nesse caso, arredondar em direção ao vizinho par.
NumberFormatter::ROUND_HALFODD: Modo de arredondamento na direção do "vizinho ímpar".
NumberFormatter::ROUND_HALFUP int: Modo de arredondamento para arredondar para o "vizinho mais próximo", a menos que ambos os vizinhos sejam equidistantes; nesse caso, arredondar para cima.
NumberFormatter::ROUND_TOWARD_ZERO: Sinônimo de NumberFormatter::ROUND_DOWN.
NumberFormatter::ROUND_UP int: Modo de arredondamento para arredondar a partir de zero.

Especificadores de Preenchimento

Valores de posição de preenchimento usados por numfmt_get_attribute() e numfmt_set_attribute() com o atributo NumberFormatter::PADDING_POSITION.

NumberFormatter::PAD_AFTER_PREFIX int: Caracteres de preenchimento inseridos após o prefixo.
NumberFormatter::PAD_AFTER_SUFFIX int: Caracteres de preenchimento inseridos após o sufixo.
NumberFormatter::PAD_BEFORE_PREFIX int: Caracteres de preenchimento inseridos antes do prefixo.
NumberFormatter::PAD_BEFORE_SUFFIX int: Caracteres de preenchimento inseridos antes do sufixo.

Veja Também

Registro de Alterações

Versão	Descrição
8.5.0	Adicionadas as constantes `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY` e `NumberFormatter::CURRENCY_STANDARD`.
8.4.0	As constantes de classe agora são tipadas.

Índice

NumberFormatter::create — Cria um formatador de número
NumberFormatter::format — Formata um número
NumberFormatter::formatCurrency — Formata um valor de moeda
NumberFormatter::getAttribute — Obtém um atributo
NumberFormatter::getErrorCode — Obtém o último código de erro do formatador
NumberFormatter::getErrorMessage — Obtém a última mensagem de erro do formatador
NumberFormatter::getLocale — Obtém a localidade do formatador
NumberFormatter::getPattern — Obtém padrão do formatador
NumberFormatter::getSymbol — Obtém um valor de símbolo
NumberFormatter::getTextAttribute — Obtém um atributo de texto
NumberFormatter::parse — Interpreta um número
NumberFormatter::parseCurrency — Interpreta um valor monetário
NumberFormatter::setAttribute — Define um atributo
NumberFormatter::setPattern — Define o padrão do formatador
NumberFormatter::setSymbol — Define um valor de símbolo
NumberFormatter::setTextAttribute — Define um atributo de texto