照合強度を設定する

# Collator::setStrength

# collator_set_strength

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

Collator::setStrength -- collator_set_strength — 照合強度を設定する

### 説明

オブジェクト指向型

public function Collator::setStrength(int `$strength`): true

手続き型

function collator_set_strength(Collator `$object`, int `$strength`): true

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

1. 第一段階 (Primary Level): 一般に、これは元となる文字自体の違いを表すものとして使用します (たとえば "a" < "b")。これが、いちばん強い違いとなります。 たとえば、辞書などではこれを用いてセクション分けしています。 これは、 `level 1` の強度 (level1 strength) ともいいます。

2. 第二段階 (Secondary Level): 文字のアクセント記号を、第二段階の違いとします (たとえば "as" < "às" < "at")。 言語によっては、その他の文字の違いも第二段階の違いとみなすこともあります。 文字列のどこかで第一段階の違いがある場合、第二段階の違いは無視します。 これは、 `level 2` の強度 (level2 strength) ともいいます。

   > 注意:

   > 注意: 言語によっては (たとえばデンマーク語)、 アクセント記号は元の文字とは別の文字とみなすものもあります。 しかし、たいていの言語では、 アクセントなしの文字とアクセントつきの文字の違いは第二段階とみなします。

3. 第三段階 (Tertiary Level): 大文字と小文字の違いを区別するのが第二段階の違いです (たとえば "ao" < "Ao" < "aò")。 さらに、ある文字とその派生形の違い(たとえば "a" and "𝒶") も第三段階と判断します。さらに、カナの大文字と小文字の違い (訳注: たとえば "や" と "ゃ") もこの段階になります。 文字列のどこかで第一段階や第二段階の違いがある場合、 第三段階の違いは無視します。 これは、`level 3` の強度 (level3 strength) ともいいます。

4. 第四段階 (Quaternary Level): レベル 1 から 3 までで句読点を無視する場合 ("句読点の無視" を参照)、 追加の段階を使用して句読点つきの単語となしの単語を区別します (たとえば "ab" < "a-b" < "aB")。 どこかに第一段階や第二段階、第三段階の違いがある場合、 第四段階の違いは無視します。 これは、 `level 4` の強度 (level4 strength) ともいいます。 第四段階を使用するのは、句読点を無視する必要がある場合や 日本語のテキスト ("ひらがなの処理" を参照) を処理する場合のみです。

5. 一致段階 (Identical Level): それ以外のすべてのレベルで等しかった場合に、最後の手段として一致段階を用います。 この段階で比較するのは、NFD 形式の文字列の Unicode コードポイントです。 レベル 1 から 4 までで違いがない場合にのみ比較します。 たとえば、ヘブライ語の朗誦記号 (cantillation mark) は、 この段階でしか識別できません。 この段階は慎重に使うようにしましょう。 ふたつの文字列でコードポイントの値のみが違うなどということは、 めったにないことだからです。 この段階を使用すると、(ソートキーの強度が上がるのと同時に) インクリメンタルな比較やソートキーの生成のパフォーマンスが劇的に低下します。 これは、`level 5` の強度 (level5 strength) ともいいます。

たとえば、「アクセントを無視」したり「アクセントと大文字小文字の区別を無視」 したりしてテキストの検索を行いたいこともあります。 ほぼすべての文字は第三段階までで識別できるので、 大半のロケールではデフォルトの指定は第三段階となっています。 しかし、場合によっては第四段階の強度を使用することになります。 これを用いると、空白や句読点や記号など、 他の強度では無視されるような違いも識別するようになります。 文字の識別を非常に厳密に行うには、一致段階の強度を使用します (たとえばこれを使用すると、Mathematical Bold Small A と Mathematical Italic Small A が別の文字とみなされます)。 しかし、第三段階を超える強度を使用すると、 ソートキーが非常に長くなってしまい、 また同じ文字列に対する比較処理も非常に遅くなってしまいます。

### パラメータ

`object`

  Collator オブジェクト。

`strength`

  設定する強度。

  以下のいずれかです。

  - `Collator::PRIMARY`

  - `Collator::SECONDARY`

  - `Collator::TERTIARY`

  - `Collator::QUATERNARY`

  - `Collator::IDENTICAL`

  - `Collator::DEFAULT_STRENGTH`

### 戻り値

常に `true` を返します。

### 例

例1 collator_set_strength() の例

    <?php
    $arr  = array( 'aò', 'Ao', 'ao' );
    $coll = collator_create( 'en_US' );

    // デフォルトの強度で配列を並べ替えます
    collator_sort( $coll, $arr );
    var_export( $arr );

    // 第一段階の強度で配列を並べ替えます
    collator_set_strength( $coll, Collator::PRIMARY );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

上の例の出力は以下となります。

    array (
      0 => 'ao',
      1 => 'Ao',
      2 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### 参考

- Collator の定数
- collator_get_strength() - 現在の照合強度を取得する

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