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

classNumberFormatter {

publicconstintPATTERN_DECIMAL;

publicconstintDECIMAL;

publicconstintCURRENCY;

publicconstintPERCENT;

publicconstintSCIENTIFIC;

publicconstintSPELLOUT;

publicconstintORDINAL;

publicconstintDURATION;

publicconstintPATTERN_RULEBASED;

publicconstintIGNORE;

publicconstintCURRENCY_ACCOUNTING;

publicconstintDEFAULT_STYLE;

publicconstintROUND_CEILING;

publicconstintROUND_FLOOR;

publicconstintROUND_DOWN;

publicconstintROUND_UP;

publicconstintROUND_HALFEVEN;

publicconstintROUND_HALFDOWN;

publicconstintROUND_HALFUP;

publicconstintPAD_BEFORE_PREFIX;

publicconstintPAD_AFTER_PREFIX;

publicconstintPAD_BEFORE_SUFFIX;

publicconstintPAD_AFTER_SUFFIX;

publicconstintPARSE_INT_ONLY;

publicconstintGROUPING_USED;

publicconstintDECIMAL_ALWAYS_SHOWN;

publicconstintMAX_INTEGER_DIGITS;

publicconstintMIN_INTEGER_DIGITS;

publicconstintINTEGER_DIGITS;

publicconstintMAX_FRACTION_DIGITS;

publicconstintMIN_FRACTION_DIGITS;

publicconstintFRACTION_DIGITS;

publicconstintMULTIPLIER;

publicconstintGROUPING_SIZE;

publicconstintROUNDING_MODE;

publicconstintROUNDING_INCREMENT;

publicconstintFORMAT_WIDTH;

publicconstintPADDING_POSITION;

publicconstintSECONDARY_GROUPING_SIZE;

publicconstintSIGNIFICANT_DIGITS_USED;

publicconstintMIN_SIGNIFICANT_DIGITS;

publicconstintMAX_SIGNIFICANT_DIGITS;

publicconstintLENIENT_PARSE;

publicconstintPOSITIVE_PREFIX;

publicconstintPOSITIVE_SUFFIX;

publicconstintNEGATIVE_PREFIX;

publicconstintNEGATIVE_SUFFIX;

publicconstintPADDING_CHARACTER;

publicconstintCURRENCY_CODE;

publicconstintDEFAULT_RULESET;

publicconstintPUBLIC_RULESETS;

publicconstintDECIMAL_SEPARATOR_SYMBOL;

publicconstintGROUPING_SEPARATOR_SYMBOL;

publicconstintPATTERN_SEPARATOR_SYMBOL;

publicconstintPERCENT_SYMBOL;

publicconstintZERO_DIGIT_SYMBOL;

publicconstintDIGIT_SYMBOL;

publicconstintMINUS_SIGN_SYMBOL;

publicconstintPLUS_SIGN_SYMBOL;

publicconstintCURRENCY_SYMBOL;

publicconstintINTL_CURRENCY_SYMBOL;

publicconstintMONETARY_SEPARATOR_SYMBOL;

publicconstintEXPONENTIAL_SYMBOL;

publicconstintPERMILL_SYMBOL;

publicconstintPAD_ESCAPE_SYMBOL;

publicconstintINFINITY_SYMBOL;

publicconstintNAN_SYMBOL;

publicconstintSIGNIFICANT_DIGIT_SYMBOL;

publicconstintMONETARY_GROUPING_SEPARATOR_SYMBOL;

publicconstintTYPE_DEFAULT;

publicconstintTYPE_INT32;

publicconstintTYPE_INT64;

publicconstintTYPE_DOUBLE;

publicconstintTYPE_CURRENCY;

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

publicstaticcreate(string$locale, int$style, ?string$pattern = null): ?NumberFormatter

publicformatCurrency(float$amount, string$currency): string|false

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

publicgetAttribute(int$attribute): int|float|false

publicgetErrorCode(): int

publicgetErrorMessage(): string

publicgetLocale(int$type = ULOC_ACTUAL_LOCALE): string|false

publicgetPattern(): string|false

publicgetSymbol(int$symbol): string|false

publicgetTextAttribute(int$attribute): string|false

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

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

publicsetAttribute(int$attribute, int|float$value): bool

publicsetPattern(string$pattern): bool

publicsetSymbol(int$symbol, string$value): bool

publicsetTextAttribute(int$attribute, string$value): bool

}

Constantes pré-definidas

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

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

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.

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).

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.

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.

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

Índice

NumberFormatter::create — Cria um formatador de número
NumberFormatter::formatCurrency — Formata um valor de moeda
NumberFormatter::format — Formata um número
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::parseCurrency — Interpreta um valor monetário
NumberFormatter::parse — Interpreta um número
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