# 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 function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function 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

- » Documentação de formatação ICU
- » Formatadores de números ICU
- » Formatadores de decimais ICU
- » Formatadores de números baseados em regras ICU

## 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open