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 のような複雑な書式を設定する場合は、 ルールベースの数値フォーマッタを使用します。

    クラス概要

    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
    }

    定義済み定数

    これらのスタイルは 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_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
    サフィックスの前にパディング文字を入れる

    目次

    To Top