# Collator クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## はじめに

各ロケール固有の並び順を考慮した文字列の比較機能を提供します。

## クラス概要

class Collator {
/* 定数 */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* メソッド */
public function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## 定義済み定数

`Collator::FRENCH_COLLATION` int

  文字列の後に続くさまざまなアクセントによる並べ替えを行います。 この属性は、フランス語などの一部のロケールでは自動的に On となります。 通常は、この属性を明示的に設定する必要はありません。 これを On にすると文字列の比較の効率が落ちますが、 ソートキーの長さは影響を受けません。 使用できる値は次のとおりです。

  - `Collator::ON`
  - `Collator::OFF`(デフォルト)
  - `Collator::DEFAULT_VALUE`

  例1 FRENCH_COLLATION のルール

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING`

  Alternate 属性は、UCA における、いわゆる "可変文字 (variable characters)"、 つまり空白や句読点、記号の処理方法を制御するものです。 Alternate を NonIgnorable (N) に設定すると、これらの文字の違いを通常の文字の違いと同じように扱います。 Alternate を Shifted (S) に設定すると、これらの文字の違いの重要度を低くします。 Shifted は、Strength を Quaternary (第四段階) に指定して使用することが多くなります。 この場合、文字列の比較において空白や句読点そして記号の違いを考慮するのは それ以外の要素 (文字、アクセント、大文字小文字) がすべて一致する場合のみとなります。 Alternate を Shifted 以外にした場合は、 Strength が 3 のときと 4 のときの違いがなくなります。 詳細な情報やサンプルは、 » UCA の Variable_Weighting を参照ください。 Alternate の値を単なる On や Off にしていない理由は、将来的にさらに別の値が追加される可能性があるからです。 UCA のオプション Blanked を表すには、Strength を 3 そして Alternate を Shifted に設定します。 大半のロケールでは、デフォルトは NonIgnorable です。 Shifted を選択すると、記号類以外が等しい文字列がたくさんあるときに処理速度が低下します。 強度レベルを上げない限り、ソートキーの長さには影響を与えません。

  使用できる値は次のとおりです。

  - `Collator::NON_IGNORABLE`(デフォルト)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  例2 ALTERNATE_HANDLING のルール

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` int

  Case_First 属性は、 文字列のその他の部分に違いがないときに 大文字と小文字のどちらが前にくるかを指定するものです。 使用できる値は、 Uppercase_First (U) と Lowercase_First (L)、そして標準の Default と Off です。 Off と Lowercase_First は、結果に関していえばほとんど違いはありません。 そのため、普通は Lowercase_First を使うことはありません。 Off あるいは Uppercase_First を使用することになります (X と L の違いを知りたい人は、`Collation Customization` を調べてください)。 L あるいは U のいずれを指定しても、文字列比較の処理速度には影響を与えません。 しかし、ソートキーの長さには影響を与えます。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  例3 CASE_FIRST のルール

  - C=X or C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` int

  Case_Level 属性は、アクセントは無視するものの大文字小文字は区別したい場合に使用します。 そんな場合は、Strength を Primary にして Case_Level を On とします。 大半のロケールでは、この設定はデフォルトで Off となっています。 この属性を On にすると、文字列の比較のパフォーマンスやソートキーに多少影響を及ぼします。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  例4 CASE_LEVEL のルール

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  Normalization 設定は、比較時にテキストを正規化するか否かを指定します。 この設定を off (多くのロケールにおけるデフォルト設定です) にしても、 一般的な使用法ではほぼ正確に利用できます (詳細は UTN #5 を参照ください)。 問題となるのは、アクセント記号が正規の位置以外に登場する場合などです。 この設定を On にすると、 どんなテキストが与えられたとしても可能な限り結果を保証するようにします。 この属性を On にすると、 文字列比較のパフォーマンスに中程度の影響を及ぼします。 影響の程度は、正規化を要する並びの登場頻度に依存します。 ソートキーの長さには、目立った影響は及ぼしません。 入力テキストが NFD あるいは NFKD 形式で正規化されている場合は、 このオプションを有効にする必要はありません。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  ICU Collation Service は、多くの比較レベルをサポートしています ("レベル" という名前ですが、"強度" と呼ばれることもあります)。 これらのカテゴリを用いることで、ICU は、 各地域の規約にあわせた適切な文字列の並べ替えを正確に行えるようになります。 また、各段階を選択して採用することで、 テキスト内の文字列検索をさまざまな条件で行うことも可能になります。 詳細な情報は collator_set_strength() を参照ください。

  使用できる値は次のとおりです。

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(デフォルト)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  JIS x 4061 との互換性を維持するには、さらなるレベルを追加して ひらがなとカタカナを区別する必要があります。 標準規格との互換性を要する場合は、この属性を On にして強度を Quaternary にしなければなりません。 これは、ソートキーの長さにも文字列比較のパフォーマンスにも影響を及ぼします。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  on にすると、数値形式の文字列の各桁を数値として使用した照合キーを生成します。 これにより、'100' のほうが '2' より「後」に並ぶようになります。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

## 目次

- Collator::asort — インデックスの情報を保持しつつ配列を並べ替える
- Collator::compare — ふたつの Unicode 文字列を比較する
- Collator::__construct — collator を作成する
- Collator::create — collator を作成する
- Collator::getAttribute — 照合用の属性の値を取得する
- Collator::getErrorCode — collator の直近のエラーコードを取得する
- Collator::getErrorMessage — collator の直近のエラーコードのテキストを取得する
- Collator::getLocale — collator のロケール名を取得する
- Collator::getSortKey — 文字列のソート用のキーを取得する
- Collator::getStrength — 現在の照合強度を取得する
- Collator::setAttribute — 照合用の属性を設定する
- Collator::setStrength — 照合強度を設定する
- Collator::sort — 指定した collator で配列を並べ替える
- Collator::sortWithSortKeys — 指定した collator とキーで配列を並べ替える

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