# 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 function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function 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
  サフィックスの前にパディング文字を入れる

## 参考

- » ICU formatting documentation
- » ICU number formatters
- » ICU decimal formatters
- » ICU rule-based number formatters

## 変更履歴

バージョン | 説明
--- | ---
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 — テキスト属性を設定する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open