NumberFormatter クラス

はじめに

プログラムで数値を保存したり操作したりする際には、ロケールに依存しないバイナリ表現を使用します。数値を表示するときに、ロケールにあわせた文字列形式に変換します。たとえば 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 のような複雑な書式を設定する場合は、ルールベースの数値フォーマッタを使用します。

クラス概要

NumberFormatter

/* 定数 */

public const int NumberFormatter::PATTERN_DECIMAL;

public const int NumberFormatter::DECIMAL;

public const int NumberFormatter::CURRENCY;

public const int NumberFormatter::PERCENT;

public const int NumberFormatter::SCIENTIFIC;

public const int NumberFormatter::SPELLOUT;

public const int NumberFormatter::ORDINAL;

public const int NumberFormatter::DURATION;

public const int NumberFormatter::PATTERN_RULEBASED;

public const int NumberFormatter::IGNORE;

public const int NumberFormatter::CURRENCY_ACCOUNTING;

public const int NumberFormatter::DEFAULT_STYLE;

public const int NumberFormatter::ROUND_CEILING;

public const int NumberFormatter::ROUND_FLOOR;

public const int NumberFormatter::ROUND_DOWN;

public const int NumberFormatter::ROUND_UP;

public const int NumberFormatter::ROUND_HALFEVEN;

public const int NumberFormatter::ROUND_HALFDOWN;

public const int NumberFormatter::ROUND_HALFUP;

public const int NumberFormatter::PAD_BEFORE_PREFIX;

public const int NumberFormatter::PAD_AFTER_PREFIX;

public const int NumberFormatter::PAD_BEFORE_SUFFIX;

public const int NumberFormatter::PAD_AFTER_SUFFIX;

public const int NumberFormatter::PARSE_INT_ONLY;

public const int NumberFormatter::GROUPING_USED;

public const int NumberFormatter::DECIMAL_ALWAYS_SHOWN;

public const int NumberFormatter::MAX_INTEGER_DIGITS;

public const int NumberFormatter::MIN_INTEGER_DIGITS;

public const int NumberFormatter::INTEGER_DIGITS;

public const int NumberFormatter::MAX_FRACTION_DIGITS;

public const int NumberFormatter::MIN_FRACTION_DIGITS;

public const int NumberFormatter::FRACTION_DIGITS;

public const int NumberFormatter::MULTIPLIER;

public const int NumberFormatter::GROUPING_SIZE;

public const int NumberFormatter::ROUNDING_MODE;

public const int NumberFormatter::ROUNDING_INCREMENT;

public const int NumberFormatter::FORMAT_WIDTH;

public const int NumberFormatter::PADDING_POSITION;

public const int NumberFormatter::SECONDARY_GROUPING_SIZE;

public const int NumberFormatter::SIGNIFICANT_DIGITS_USED;

public const int NumberFormatter::MIN_SIGNIFICANT_DIGITS;

public const int NumberFormatter::MAX_SIGNIFICANT_DIGITS;

public const int NumberFormatter::LENIENT_PARSE;

public const int NumberFormatter::POSITIVE_PREFIX;

public const int NumberFormatter::POSITIVE_SUFFIX;

public const int NumberFormatter::NEGATIVE_PREFIX;

public const int NumberFormatter::NEGATIVE_SUFFIX;

public const int NumberFormatter::PADDING_CHARACTER;

public const int NumberFormatter::CURRENCY_CODE;

public const int NumberFormatter::DEFAULT_RULESET;

public const int NumberFormatter::PUBLIC_RULESETS;

public const int NumberFormatter::DECIMAL_SEPARATOR_SYMBOL;

public const int NumberFormatter::GROUPING_SEPARATOR_SYMBOL;

public const int NumberFormatter::PATTERN_SEPARATOR_SYMBOL;

public const int NumberFormatter::PERCENT_SYMBOL;

public const int NumberFormatter::ZERO_DIGIT_SYMBOL;

public const int NumberFormatter::DIGIT_SYMBOL;

public const int NumberFormatter::MINUS_SIGN_SYMBOL;

public const int NumberFormatter::PLUS_SIGN_SYMBOL;

public const int NumberFormatter::CURRENCY_SYMBOL;

public const int NumberFormatter::INTL_CURRENCY_SYMBOL;

public const int NumberFormatter::MONETARY_SEPARATOR_SYMBOL;

public const int NumberFormatter::EXPONENTIAL_SYMBOL;

public const int NumberFormatter::PERMILL_SYMBOL;

public const int NumberFormatter::PAD_ESCAPE_SYMBOL;

public const int NumberFormatter::INFINITY_SYMBOL;

public const int NumberFormatter::NAN_SYMBOL;

public const int NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL;

public const int NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL;

public const int NumberFormatter::TYPE_DEFAULT;

public const int NumberFormatter::TYPE_INT32;

public const int NumberFormatter::TYPE_INT64;

public const int NumberFormatter::TYPE_DOUBLE;

public const int NumberFormatter::TYPE_CURRENCY;

/* メソッド */

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

public static NumberFormatternull create(string $locale, int $style, stringnull $pattern = null)

public stringfalse format(intfloat $num, int $type = NumberFormatter::TYPE_DEFAULT)

public stringfalse formatCurrency(float $amount, string $currency)

public intfloatfalse getAttribute(int $attribute)

public int getErrorCode()

public string getErrorMessage()

public stringfalse getLocale(int $type = ULOC_ACTUAL_LOCALE)

public stringfalse getPattern()

public stringfalse getSymbol(int $symbol)

public stringfalse getTextAttribute(int $attribute)

public intfloatfalse parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null)

public floatfalse parseCurrency(string $string, string &$currency, int &$offset = null)

public bool setAttribute(int $attribute, intfloat $value)

public bool setPattern(string $pattern)

public bool setSymbol(int $symbol, string $value)

public bool setTextAttribute(int $attribute, string $value)

定義済み定数

フォーマッタのタイプ

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

NumberFormatter::PATTERN_DECIMAL int: パターンで定義する十進形式
NumberFormatter::DECIMAL int: 十進形式
NumberFormatter::CURRENCY int: 通貨形式
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_CEILING int: 正の無限大に向けて丸めるモード
NumberFormatter::ROUND_DOWN int: ゼロに向けて丸めるモード
NumberFormatter::ROUND_FLOOR int: 負の無限大に向けて丸めるモード
NumberFormatter::ROUND_HALFDOWN int: "一番近いところ" に向けて丸めるモード。両方から等距離にある場合はゼロに向けて丸めます。
NumberFormatter::ROUND_HALFEVEN int: "一番近いところ" に向けて丸めるモード。両方から等距離にある場合は偶数になるように丸めます。
NumberFormatter::ROUND_HALFUP int: "一番近いところ" に向けて丸めるモード。両方から等距離にある場合はゼロから離れる方向に丸めます。
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.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 — テキスト属性を設定する