NumberFormatter クラス

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

はじめに

プログラムで数値を保存したり操作したりする際には、ロケールに依存しないバイナリ表現を使用します。数値を表示するときに、ロケールにあわせた文字列形式に変換します。たとえば 12345.67 という数値の表記はアメリカでは "12,345.67"、フランスでは "12 345,67"、そしてドイツでは "12.345,67" となります。

NumberFormatter クラスのメソッドを実行すると、数値や通貨、パーセンテージなどの値をロケールに応じた形式にフォーマットすることができます。 NumberFormatter はロケールを考慮した処理を行うので、ロケールごとに別の NumberFormatter を用意する必要があります。 NumberFormatter のメソッドは、浮動小数点数値のような数値をロケールにあわせた文字列に変換します。

通貨の場合は、通貨用の書式を使用してフォーマッタを作成します。これは、ロケールにあわせて数値を適切な書式にして通貨記号をつけた文字列を返します。もちろん、NumberFormatter クラスは為替レートの変換などは考慮しません。指定した通貨にかかわらず、出力される数値は同じものとなります。つまり、ロケールによって同じ数値が違う額を表すことになるということです。 9988776.65 という数値を指定したときの結果は次のようになります。

9 988 776,65 € (フランス)
9.988.776,65 € (ドイツ)
$9,988,776.65 (アメリカ)

パーセンテージをフォーマットするには、パーセンテージ用の書式を指定したフォーマッタを作成します。これを使用すると、たとえば 0.75 のような小数が 75% と表示されるようになります。

spelled-out numbers のような複雑な書式を設定する場合は、ルールベースの数値フォーマッタを使用します。

クラス概要

class NumberFormatter {

/* 定数 */

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;

/* メソッド */

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

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

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

public format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): 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 parseCurrency(string $string, string &$currency, int &$offset = null): float|false

public parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|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

}

定義済み定数

これらのスタイルは numfmt_create() で使用するもので、フォーマッタの形式を定義します。

NumberFormatter::PATTERN_DECIMAL: パターンで定義する十進形式
NumberFormatter::DECIMAL: 十進形式
NumberFormatter::CURRENCY: 通貨形式
NumberFormatter::PERCENT: パーセント形式
NumberFormatter::SCIENTIFIC: 科学形式
NumberFormatter::SPELLOUT: ルールベースの省略しない形式
NumberFormatter::ORDINAL: ルールベースの序数形式
NumberFormatter::DURATION: ルールベースの連続形式
NumberFormatter::PATTERN_RULEBASED: パターンで定義するルールベースの形式
NumberFormatter::CURRENCY_ACCOUNTING: 会計処理のための通貨フォーマット。例: 負の通貨量の場合、-$3.00 ではなく、($3.00) になります。 PHP 7.4.1 と ICU 53 から利用可能です。
NumberFormatter::DEFAULT_STYLE: そのロケールのデフォルトの形式
NumberFormatter::IGNORE: PATTERN_DECIMAL のエイリアス

これらの定数は、数値のパースやフォーマットの方法を定義します。 numfmt_format() や numfmt_parse() の引数として使用します。

NumberFormatter::TYPE_DEFAULT: 変数の型に由来する型
NumberFormatter::TYPE_INT32: 32 ビット整数値としてフォーマット/パースする
NumberFormatter::TYPE_INT64: 64 ビット整数値としてフォーマット/パースする
NumberFormatter::TYPE_DOUBLE: 浮動小数点数値としてフォーマット/パースする
NumberFormatter::TYPE_CURRENCY: 通貨値としてフォーマット/パースする。PHP 8.3.0 以降は非推奨

numfmt_get_attribute() および numfmt_set_attribute() で使用する数値フォーマット属性です。

NumberFormatter::PARSE_INT_ONLY: 整数値のみをパースする
NumberFormatter::GROUPING_USED: グループ区切り文字を使用する
NumberFormatter::DECIMAL_ALWAYS_SHOWN: 常に小数点を表示する
NumberFormatter::MAX_INTEGER_DIGITS: 整数部の最大桁数
NumberFormatter::MIN_INTEGER_DIGITS: 整数部の最小桁数
NumberFormatter::INTEGER_DIGITS: 整数部の桁数
NumberFormatter::MAX_FRACTION_DIGITS: 小数部の最大桁数
NumberFormatter::MIN_FRACTION_DIGITS: 小数部の最小桁数
NumberFormatter::FRACTION_DIGITS: 小数部の桁数
NumberFormatter::MULTIPLIER: 乗数
NumberFormatter::GROUPING_SIZE: グループ化のサイズ
NumberFormatter::ROUNDING_MODE: 丸めモード
NumberFormatter::ROUNDING_INCREMENT: 切り上げ
NumberFormatter::FORMAT_WIDTH: format() の出力のパディング幅
NumberFormatter::PADDING_POSITION: パディングを行う位置。使用できる引数の値についてはパディング位置に関する定数を参照ください。
NumberFormatter::SECONDARY_GROUPING_SIZE: 第二段階のグループ化のサイズ
NumberFormatter::SIGNIFICANT_DIGITS_USED: 有効数字を使用する
NumberFormatter::MIN_SIGNIFICANT_DIGITS: 有効数字の最小桁数
NumberFormatter::MAX_SIGNIFICANT_DIGITS: 有効数字の最大桁数
NumberFormatter::LENIENT_PARSE: ルールベースのフォーマットで使用する Lenient パースモード

numfmt_get_text_attribute() および numfmt_set_text_attribute() で使用する数値フォーマットテキスト属性です。

NumberFormatter::POSITIVE_PREFIX: 正の数のプレフィックス
NumberFormatter::POSITIVE_SUFFIX: 正の数のサフィックス
NumberFormatter::NEGATIVE_PREFIX: 負の数のプレフィックス
NumberFormatter::NEGATIVE_SUFFIX: 負の数のサフィックス
NumberFormatter::PADDING_CHARACTER: 余白を埋める際に使用する文字
NumberFormatter::CURRENCY_CODE: ISO 通貨コード
NumberFormatter::DEFAULT_RULESET: デフォルトのルールセット。ルールベースのフォーマッタでのみ有効です。
NumberFormatter::PUBLIC_RULESETS: パブリックルールセット。これは、ルールベースのフォーマッタでのみ有効です。これは読み込み専用の属性です。パブリックルールセットは文字列として返され、個々のルールセットは ';' (セミコロン) で区切られています。

numfmt_get_symbol() および numfmt_set_symbol() で使用する数値フォーマット記号です。

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL: 小数点
NumberFormatter::GROUPING_SEPARATOR_SYMBOL: グループ区切り文字
NumberFormatter::PATTERN_SEPARATOR_SYMBOL: パターン区切り文字
NumberFormatter::PERCENT_SYMBOL: パーセント記号
NumberFormatter::ZERO_DIGIT_SYMBOL: ゼロ
NumberFormatter::DIGIT_SYMBOL: パターン内で数字を表す文字
NumberFormatter::MINUS_SIGN_SYMBOL: マイナス記号
NumberFormatter::PLUS_SIGN_SYMBOL: プラス記号
NumberFormatter::CURRENCY_SYMBOL: 通貨記号
NumberFormatter::INTL_CURRENCY_SYMBOL: 国際通貨記号
NumberFormatter::MONETARY_SEPARATOR_SYMBOL: 金額の区切り文字
NumberFormatter::EXPONENTIAL_SYMBOL: 指数記号
NumberFormatter::PERMILL_SYMBOL: パーミル記号
NumberFormatter::PAD_ESCAPE_SYMBOL: パディング文字のエスケープ記号
NumberFormatter::INFINITY_SYMBOL: 無限大記号
NumberFormatter::NAN_SYMBOL: 非数値記号
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL: 有効数字記号
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL: 金額のグループ区切り文字

numfmt_get_attribute() および numfmt_set_attribute() で、 NumberFormatter::ROUNDING_MODE 属性に使用する丸めモードの値です。

NumberFormatter::ROUND_CEILING: 正の無限大に向けて丸めるモード
NumberFormatter::ROUND_DOWN: ゼロに向けて丸めるモード
NumberFormatter::ROUND_FLOOR: 負の無限大に向けて丸めるモード
NumberFormatter::ROUND_HALFDOWN: "一番近いところ" に向けて丸めるモード。両方から等距離にある場合はゼロに向けて丸めます。
NumberFormatter::ROUND_HALFEVEN: "一番近いところ" に向けて丸めるモード。両方から等距離にある場合は偶数になるように丸めます。
NumberFormatter::ROUND_HALFUP: "一番近いところ" に向けて丸めるモード。両方から等距離にある場合はゼロから離れる方向に丸めます。
NumberFormatter::ROUND_UP: ゼロから離れる方向に丸めるモード

numfmt_get_attribute() および numfmt_set_attribute() で、 NumberFormatter::PADDING_POSITION 属性に使用するパディング位置の値です。

NumberFormatter::PAD_AFTER_PREFIX: プレフィックスの後にパディング文字を入れる
NumberFormatter::PAD_AFTER_SUFFIX: サフィックスの後にパディング文字を入れる
NumberFormatter::PAD_BEFORE_PREFIX: プレフィックスの前にパディング文字を入れる
NumberFormatter::PAD_BEFORE_SUFFIX: サフィックスの前にパディング文字を入れる

参考

NumberFormatter::create — 数値フォーマッタを作成する
NumberFormatter::formatCurrency — 通貨の値をフォーマットする
NumberFormatter::format — 数値をフォーマットする
NumberFormatter::getAttribute — 属性を取得する
NumberFormatter::getErrorCode — フォーマッタの直近のエラーコードを取得する
NumberFormatter::getErrorMessage — フォーマッタの直近のエラーメッセージを取得する
NumberFormatter::getLocale — フォーマッタのロケールを取得する
NumberFormatter::getPattern — フォーマッタのパターンを取得する
NumberFormatter::getSymbol — 記号を取得する
NumberFormatter::getTextAttribute — テキストの属性を取得する
NumberFormatter::parseCurrency — 通貨をパースする
NumberFormatter::parse — 数値をパースする
NumberFormatter::setAttribute — 属性を設定する
NumberFormatter::setPattern — フォーマッタのパターンを設定する
NumberFormatter::setSymbol — 記号の値を設定する
NumberFormatter::setTextAttribute — テキスト属性を設定する

add a note

User Contributed Notes 9 notes

down

giorgio dot liscio at email dot it ¶

13 years ago


this class seems to be painful: it is not, formatting and parsing are highly customizable, but what you probably need is really simple:



if you want to localize a number use:



<?php

$a = new \NumberFormatter("it-IT", \NumberFormatter::DECIMAL);

echo $a->format(12345.12345) . "<br>"; // outputs 12.345,12

$a->setAttribute(\NumberFormatter::MIN_FRACTION_DIGITS, 0);

$a->setAttribute(\NumberFormatter::MAX_FRACTION_DIGITS, 100); // by default some locales got max 2 fraction digits, that is probably not what you want

echo $a->format(12345.12345) . "<br>"; // outputs 12.345,12345

?>



if you want to print money use:



<?php

$a = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);

echo $a->format(12345.12345) . "<br>"; // outputs €12.345,12

?>



if you have money data stored as (for example) US dollars and you want to print them using the it-IT notation, you need to use



<?php

$a = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);

echo $a->formatCurrency(12345, "USD") . "<br>"; // outputs $ 12.345,00 and it is formatted using the italian notation (comma as decimal separator)

?>



another useful example about currency (how to obtain the currency name by a locale string):



<?php

$frontEndFormatter = new \NumberFormatter("it-IT", \NumberFormatter::CURRENCY);

$adminFormatter = new \NumberFormatter("en-US", \NumberFormatter::CURRENCY);

$symbol = $adminFormatter->getSymbol(\NumberFormatter::INTL_CURRENCY_SYMBOL); // got USD

echo $frontEndFormatter->formatCurrency(12345.12345,  $symbol) . "<br>";

?>

down

stan at dragnev dot ca ¶

4 years ago


Here's an example of how to use PATTERN_DECIMAL to print a number with two fraction digits, use () for negative numbers and pad to five characters to the left of the decimal point, using spaces as the padding character:

<?php

$fmt = new NumberFormatter("en-CA", NumberFormatter::PATTERN_DECIMAL, "* #####.00 ;(* #####.00)");
echo $fmt->format(-45.1);

// Outputs: "  (45.10)"

?>

Note that the ; in the pattern denotes the beginning of a subpattern, which is used for negative numbers. Hence the brackets around the pattern after the semicolon.

down

Einenlum ¶

10 months ago


Be aware that (at least with the locale 'fr-FR') NumberFormatter doesn't use spaces. It doesn't even use non breakable spaces (NBSP). It uses narrow non breakable spaces (NNBSP). This broke my tests.

<?php

$formatter = new NumberFormatter(
    'fr-FR',
    NumberFormatter::DEFAULT_STYLE
);

$value = $formatter->format(100_000); // '100 000'

// If you want to replace narrow non breakable spaces with non breakable spaces:

str_replace("\u{202F}", "\u{00A0}", $value);

// If you want to replace it with a normal space

str_replace("\u{202F}", " ", $value);

down

gwyneth dot llewelyn at gwynethllewelyn dot net ¶

2 years ago


When using the `NumberFormatter` class for pretty-printing currency in PHP 7.3 and 8+, it's not clear from the documentation that you can use the empty string "" as the locale for the constructor, and that will retrieve the default locale (whatever it has been set to in your environment).

`formatCurrency()`, by contrast, does not accept the empty string for the default currency symbol; it will display a 'generic' currency symbol instead (¤).

Tested with PHP 7.4.30, 8.0.21, 8.1.8 under Ubuntu Linux and 8.1.8 under macOS Big Sur (11.6.8). I tried under other alternatives (e.g. Linux running on ARM chips, PHP 7.3.3) but sadly the `NumberFormatter` library does not seem to be present (or could not be found) on those systems...

down

sudheer at binaryvibes dot co dot in ¶

13 years ago


Sample script to print number in English.

<?php
$f = new NumberFormatter("en", NumberFormatter::SPELLOUT);
echo $f->format(123456);

?>

Produces the result:
one hundred twenty-three thousand four hundred fifty-six

down

-2

AF ¶

4 years ago


Please pay attention to the Arabic decimal separator (https://en.wikipedia.org/wiki/Decimal_separator#Other_numeral_systems).

All the following conditions are true:
<?php
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) === '٫';
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) == '٫';

(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) !== ',';
(new \NumberFormatter("ar_AE", \NumberFormatter::DEFAULT_STYLE))->getSymbol(\NumberFormatter::DECIMAL_SEPARATOR_SYMBOL) != ',';
?>

down

-3

Joey ¶

7 years ago


Be warned that this class sometimes lacks sufficient error output. I recently instantiated it while invalid pattern to the constructor.

    php -r '$nf = new \NumberFormatter("tlh-KX.UTF8", \NumberFormatter::IGNORE, "{,,#;#}");var_dump($nf->format(5));'

    Fatal error: Call to a member function format() on null in Command line code on line 1

Rather than emitting an error message or throwing an exception null is returned after calling new.

I'm not sure if it's fixed in PHP 7 but it's something to watch out for. Make sure you check your parameters very closely.

down

-1

jimbo2150 at gmail dot com ¶

1 year ago


The NumberFormatter class can be used to convert integer numbers to Roman numerals without a custom function using an array of symbols and associated values:

<?php

function intToRomanNumeral(int $num) {
    static $nf = new NumberFormatter('@numbers=roman', NumberFormatter::DECIMAL);
    return $nf->format($num);
}

echo intToRomanNumeral(2); // II

echo intToRomanNumeral(5); // V

echo intToRomanNumeral(10); // X

echo intToRomanNumeral(50); // L

echo intToRomanNumeral(57); // LVII
echo intToRomanNumeral(58); // LVIII

echo intToRomanNumeral(100); // C

echo intToRomanNumeral(150); // CL

echo intToRomanNumeral(1000); // M

echo intToRomanNumeral(10000); // ↂ

?>

down

-11

Adam ¶

7 years ago


Good to know Numberformatter::SPELLOUT using soft hypens.

So, if you want to avoid it use preg_replace:

<?php
$azaz = new NumberFormatter("hu-HU", NumberFormatter::SPELLOUT);
$text = preg_replace('~\x{00AD}~u', '', $azaz->format(123456));
print $text;
?>
Output without preg_replace:
egy-száz-huszon-három-ezer négy-száz-ötven-hat

Output with preg_replace:
egyszázhuszonháromezer négyszázötvenhat

add a note

NumberFormatter クラス

はじめに

クラス概要

定義済み定数

参考

目次

User Contributed Notes 9 notes