# Collator クラス

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

## はじめに

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

## クラス概要

Collator {
/* メソッド */
public __construct ( string `$locale` )
public asort ( array `&$arr` [, int `$sort_flag` ] ) : bool
public compare ( string `$str1` , string `$str2` ) : int
public static create ( string `$locale` ) : Collator
public getAttribute ( int `$attr` ) : int
public getErrorCode ( void ) : int
public getErrorMessage ( void ) : string
public getLocale ( int `$type` ) : string
public getSortKey ( string `$str` ) : string
public getStrength ( void ) : int
public setAttribute ( int `$attr` , int `$val` ) : bool
public setStrength ( int `$strength` ) : bool
public sortWithSortKeys ( array `&$arr` ) : bool
public sort ( array `&$arr` [, int `$sort_flag` ] ) : bool
}

## 定義済み定数

`Collator::FRENCH_COLLATION` (integer)

  文字列の後に続くさまざまなアクセントによる並べ替えを行います。 この属性は、フランス語などの一部のロケールでは自動的に 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` (integer)

  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` (integer)

  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` (integer)

  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` (integer)

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

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

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

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

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

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

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

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

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

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

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

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

## 目次

- 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::sortWithSortKeys — 指定した collator とキーで配列を並べ替える
- Collator::sort — 指定した collator で配列を並べ替える