指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する

# substr_compare

(PHP 5, PHP 7, PHP 8)

substr_compare — 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する

### 説明

function substr_compare(
string `$haystack`,
string `$needle`,
int `$offset`,
?int `$length` = `null`,
bool `$case_insensitive` = `false`
): int

substr_compare() は、`haystack` の `offset` 文字目以降の最大 `length` 文字を、`needle` と比較します。

### パラメータ

`haystack`

  比較したい最初の文字列。

`needle`

  比較したい二番目の文字列。

`offset`

  比較を開始する位置。 負の値を指定した場合は、文字列の最後から数えます。

`length`

  比較する長さ。デフォルト値は、 `haystack` の長さから `offset` を引いたものと `needle` の長さのうち、長いほうです。

`case_insensitive`

  `case_insensitive` が `true` の場合、 大文字小文字を区別せずに比較します。

### 戻り値

`string1` が `string2` より小さければ 0 より小さな値を、 `string1` が `string2` より大きければ 0 より大きな値を、 両者が等しければ `0` を返します。 返却される値の絶対値に、特に意味はありません。

`offset` が `haystack` と等しい (PHP 7.2.18, 7.3.5 より前のバージョン) か、 `haystack` より長い場合、 もしくは `length` が設定されていて0未満である場合、 substr_compare() は警告を表示して `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.2.0 | この関数は、2つの文字列の長さが等しくない場合に `strlen($string1) - strlen($string2)` を返すとは限らなくなりました。 代わりに、`-1` や `1` を返す可能性があります。
8.0.0 | `length` は、nullable になりました。
7.2.18, 7.3.5 | `offset` の値は、 `haystack` の長さと等しくても問題なくなりました。

### 例

例1 substr_compare() の例

    <?php
    echo substr_compare("abcde", "bc", 1, 2), PHP_EOL; // 0
    echo substr_compare("abcde", "de", -2, 2), PHP_EOL; // 0
    echo substr_compare("abcde", "bcg", 1, 2), PHP_EOL; // 0
    echo substr_compare("abcde", "BC", 1, 2, true), PHP_EOL; // 0
    echo substr_compare("abcde", "bc", 1, 3), PHP_EOL; // 1
    echo substr_compare("abcde", "cd", 1, 2), PHP_EOL; // -1
    echo substr_compare("abcde", "abc", 5, 1), PHP_EOL; // -1
    ?>

### 参考

- strncmp() - 最初の n 文字についてバイナリセーフな文字列比較を行う

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