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

public const int DECIMAL_COMPACT_LONG;

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

public const int CURRENCY_PLURAL;

public const int CURRENCY_ACCOUNTING;

public const int CASH_CURRENCY;

public const int CURRENCY_STANDARD;

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

public const int ROUND_AWAY_FROM_ZERO;

public const int ROUND_HALFEVEN;

public const int ROUND_HALFODD;

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

}

定義済み定数

フォーマッタのタイプ

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

NumberFormatter::PATTERN_DECIMAL int: パターンで定義する十進形式
NumberFormatter::DECIMAL int: 十進形式
NumberFormatter::DECIMAL_COMPACT_SHORT int: コンパクト表記（短縮形）を使った十進形式。例: "23K", "45B"。PHP 8.5.0 および ICU 56 以降で利用可能です。
NumberFormatter::DECIMAL_COMPACT_LONG int: コンパクト表記（長い形式）を使った十進形式。例: "23 thousand", "45 billion"。PHP 8.5.0 および ICU 56 以降で利用可能です。
NumberFormatter::CURRENCY int: 通貨形式
NumberFormatter::CURRENCY_ISO int: ISO 通貨形式（例: "USD1.00"）。PHP 8.5.0 以降で利用可能です。
NumberFormatter::CURRENCY_PLURAL int: 複数形の通貨形式（例: "1.00 US dollar" および "3.00 US dollars"）。PHP 8.5.0 以降で利用可能です。
NumberFormatter::CASH_CURRENCY int: 現金使用時の通貨記号。例: "NT$3.23" ではなく "NT$3"。PHP 8.5.0 および ICU 54 以降で利用可能です。
NumberFormatter::CURRENCY_STANDARD int: 通貨記号。例: "$1.00"。負の値には非会計方式（例: マイナス記号）を使用します。PHP 8.5.0 および ICU 56 以降で利用可能です。
NumberFormatter::PERCENT int: パーセント形式
NumberFormatter::SCIENTIFIC int: 科学形式
NumberFormatter::SPELLOUT int: ルールベースの省略しない形式
NumberFormatter::ORDINAL int: ルールベースの序数形式
NumberFormatter::DURATION int: ルールベースの連続形式
NumberFormatter::PATTERN_RULEBASED int: パターンで定義するルールベースの形式
NumberFormatter::CURRENCY_ACCOUNTING int: 会計処理のための通貨フォーマット。例: 負の通貨量の場合、-$3.00 ではなく、($3.00) になります。 PHP 7.4.1 と ICU 53 から利用可能です。
NumberFormatter::DEFAULT_STYLE int: そのロケールのデフォルトの形式
NumberFormatter::IGNORE int: PATTERN_DECIMAL のエイリアス

数値フォーマットの指定子

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

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

数値フォーマットの属性

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

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

数値フォーマットのテキスト属性

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

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

シンボルフォーマットの指定子

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

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

丸めモード

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

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

パディングの指定子

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

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

参考

変更履歴

バージョン	説明
8.5.0	`NumberFormatter::DECIMAL_COMPACT_SHORT`、`NumberFormatter::DECIMAL_COMPACT_LONG`、 `NumberFormatter::CURRENCY_ISO`、`NumberFormatter::CURRENCY_PLURAL`、 `NumberFormatter::CASH_CURRENCY`、`NumberFormatter::CURRENCY_STANDARD` が追加されました。
8.4.0	クラス定数が型付けされました。

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