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 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_ACCOUNTING;

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_HALFEVEN;

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 pré-definidas

Tipos de Formato

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

NumberFormatter::PATTERN_DECIMAL: Formato decimal definido por modelo
NumberFormatter::DECIMAL: Formato decimal
NumberFormatter::CURRENCY: Formato de moeda
NumberFormatter::PERCENT: Formato de percentual
NumberFormatter::SCIENTIFIC: Formato científico
NumberFormatter::SPELLOUT: Formato baseado em regras ortográficas
NumberFormatter::ORDINAL: Formato baseado em regras ordinais
NumberFormatter::DURATION: Formato baseado em regras de duração
NumberFormatter::PATTERN_RULEBASED: Formato baseado em regras definido por modelo
NumberFormatter::CURRENCY_ACCOUNTING: 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: Formato padrão para a localidade
NumberFormatter::IGNORE: 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: Deriva o tipo a partir do tipo da variável
NumberFormatter::TYPE_INT32: Formata/analisa como um inteiro de 32 bits
NumberFormatter::TYPE_INT64: Formata/analisa como um inteiro de 64 bits
NumberFormatter::TYPE_DOUBLE: Formata/analisa como um valor de ponto flutuante
NumberFormatter::TYPE_CURRENCY: Formata/analisa como um valor de moeda. Defasado 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: Analisa inteiros somente.
NumberFormatter::GROUPING_USED: Usa separador de agrupamento.
NumberFormatter::DECIMAL_ALWAYS_SHOWN: Sempre mostra o separador de decimais.
NumberFormatter::MAX_INTEGER_DIGITS: Máximo de dígitos inteiros.
NumberFormatter::MIN_INTEGER_DIGITS: Mínimo de dígitos inteiros.
NumberFormatter::INTEGER_DIGITS: Dígitos inteiros.
NumberFormatter::MAX_FRACTION_DIGITS: Máximo de dígitos decimais.
NumberFormatter::MIN_FRACTION_DIGITS: Mínimo de dígitos decimais.
NumberFormatter::FRACTION_DIGITS: Dígitos decimais.
NumberFormatter::MULTIPLIER: Multiplicador.
NumberFormatter::GROUPING_SIZE: Tamanho do agrupamento.
NumberFormatter::ROUNDING_MODE: Modo de arredondamento.
NumberFormatter::ROUNDING_INCREMENT: Incremento de arredondamento.
NumberFormatter::FORMAT_WIDTH: A largura para a qual a saída de format() será preenchida.
NumberFormatter::PADDING_POSITION: 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: Tamanho de agrupamento secundário.
NumberFormatter::SIGNIFICANT_DIGITS_USED: Usa dígitos significativos.
NumberFormatter::MIN_SIGNIFICANT_DIGITS: Mínimo de dígitos significativos.
NumberFormatter::MAX_SIGNIFICANT_DIGITS: Máximo de dígitos significativos.
NumberFormatter::LENIENT_PARSE: 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: Prefixo positivo.
NumberFormatter::POSITIVE_SUFFIX: Sufixo positivo.
NumberFormatter::NEGATIVE_PREFIX: Prefixo negativo.
NumberFormatter::NEGATIVE_SUFFIX: Sufixo negativo.
NumberFormatter::PADDING_CHARACTER: O caractere usado para preencher a largura do formato.
NumberFormatter::CURRENCY_CODE: O código de moeda ISO.
NumberFormatter::DEFAULT_RULESET: O conjunto de regras padrão. Isso está disponível apenas com formatadores baseados em regras.
NumberFormatter::PUBLIC_RULESETS: 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: O separador de decimais.
NumberFormatter::GROUPING_SEPARATOR_SYMBOL: O separador de agrupamento.
NumberFormatter::PATTERN_SEPARATOR_SYMBOL: O separador de padrão.
NumberFormatter::PERCENT_SYMBOL: O sinal de percentagem.
NumberFormatter::ZERO_DIGIT_SYMBOL: Zero.
NumberFormatter::DIGIT_SYMBOL: Caractere representando um dígito no padrão.
NumberFormatter::MINUS_SIGN_SYMBOL: O sinal de menos.
NumberFormatter::PLUS_SIGN_SYMBOL: O sinal de mais.
NumberFormatter::CURRENCY_SYMBOL: O símbolo da moeda.
NumberFormatter::INTL_CURRENCY_SYMBOL: O símbolo internacional da moeda.
NumberFormatter::MONETARY_SEPARATOR_SYMBOL: O separador monetário.
NumberFormatter::EXPONENTIAL_SYMBOL: O símbolo exponencial.
NumberFormatter::PERMILL_SYMBOL: O símbolo de permilagem.
NumberFormatter::PAD_ESCAPE_SYMBOL: Caractere de preenchimento de escape.
NumberFormatter::INFINITY_SYMBOL: Símbolo de infinito.
NumberFormatter::NAN_SYMBOL: Símbolo representando que o valor não é um número.
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL: Símbolo de dígito significativo.
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL: 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_CEILING: Modo de arredondamento para arredondar em direção ao infinito positivo.
NumberFormatter::ROUND_DOWN: Modo de arredondamento para arredondar para zero.
NumberFormatter::ROUND_FLOOR: Modo de arredondamento para arredondar em direção ao infinito negativo.
NumberFormatter::ROUND_HALFDOWN: 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: 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_HALFUP: 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_UP: 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: Caracteres de preenchimento inseridos após o prefixo.
NumberFormatter::PAD_AFTER_SUFFIX: Caracteres de preenchimento inseridos após o sufixo.
NumberFormatter::PAD_BEFORE_PREFIX: Caracteres de preenchimento inseridos antes do prefixo.
NumberFormatter::PAD_BEFORE_SUFFIX: Caracteres de preenchimento inseridos antes do sufixo.

Veja Também

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