NumberFormatter クラス

(PHP 5 >= 5.3.0, PHP 7, 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 in (アメリカ)

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

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

クラス概要

NumberFormatter {
/* メソッド */
public __construct ( string $locale , int $style [, string $pattern ] )
public static NumberFormatter create ( string $locale , int $style [, string $pattern ] )
public string formatCurrency ( float $value , string $currency )
public string format ( number $value [, int $type ] )
public int getAttribute ( int $attr )
public int getErrorCode ( void )
public string getErrorMessage ( void )
public string getLocale ([ int $type ] )
public string getPattern ( void )
public string getSymbol ( int $attr )
public string getTextAttribute ( int $attr )
public float parseCurrency ( string $value , string &$currency [, int &$position ] )
public mixed parse ( string $value [, int $type [, int &$position ]] )
public bool setAttribute ( int $attr , int $value )
public bool setPattern ( string $pattern )
public bool setSymbol ( int $attr , string $value )
public bool setTextAttribute ( int $attr , string $value )
}

定義済み定数

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

NumberFormatter::PATTERN_DECIMAL (integer)
パターンで定義する十進形式
NumberFormatter::DECIMAL (integer)
十進形式
NumberFormatter::CURRENCY (integer)
通貨形式
NumberFormatter::PERCENT (integer)
パーセント形式
NumberFormatter::SCIENTIFIC (integer)
科学形式
NumberFormatter::SPELLOUT (integer)
ルールベースの省略しない形式
NumberFormatter::ORDINAL (integer)
ルールベースの序数形式
NumberFormatter::DURATION (integer)
ルールベースの連続形式
NumberFormatter::PATTERN_RULEBASED (integer)
パターンで定義するルールベースの形式
NumberFormatter::DEFAULT_STYLE (integer)
そのロケールのデフォルトの形式
NumberFormatter::IGNORE (integer)
PATTERN_DECIMAL のエイリアス

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

NumberFormatter::TYPE_DEFAULT (integer)
変数の型に由来する型
NumberFormatter::TYPE_INT32 (integer)
32 ビット整数値としてフォーマット/パースする
NumberFormatter::TYPE_INT64 (integer)
64 ビット整数値としてフォーマット/パースする
NumberFormatter::TYPE_DOUBLE (integer)
浮動小数点数値としてフォーマット/パースする
NumberFormatter::TYPE_CURRENCY (integer)
通貨値としてフォーマット/パースする

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

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

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

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

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

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

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

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

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

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

目次

add a note add a note

User Contributed Notes 4 notes

up
21
giorgio dot liscio at email dot it
6 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>";
?>
up
6
sudheer at binaryvibes dot co dot in
6 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
up
1
Adam
9 months 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
up
0
Joey
8 months 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.
To Top