substr_compare

(PHP 5, PHP 7, PHP 8)

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

説明

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 の長さと等しくても問題なくなりました。

バージョン	説明
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 文字についてバイナリセーフな文字列比較を行う