pattern で指定した正規表現により subject を検索します。
matches を指定した場合、検索結果が代入されます。 $matches[0] にはパターン全体にマッチしたテキストが代入され、 $matches[1] には 1 番目ののキャプチャ用サブパターンにマッチした 文字列が代入され、といったようになります。
flags には以下のフラグを指定できます。
このフラグを設定した場合、各マッチに対応する文字列のオフセットも返されます。 これにより、返り値は配列となり、配列の要素 0 はマッチした文字列、 要素 1は対象文字列中におけるマッチした文字列のオフセット値 となることに注意してください。 このフラグは、PHP 4.3.0 以降で利用可能です。
通常、検索は対象文字列の先頭から開始されます。 オプションのパラメータ offset を使用して 検索の開始位置を指定することも可能です。 offsetパラメータは、PHP 4.3.3 以降で使用できます。
注意: offset を用いるのと、 substr($subject, $offset) を preg_match_all()の対象文字列として指定するのとは 等価ではありません。 これは、pattern には、 ^, $ や (?<=x) のような言明を含めることができるためです。 以下を比べてみてください。
<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
print_r($matches);
?>上の例の出力は以下となります。
Array ( )一方、この例を見てください。
<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>出力は以下のようになります。
Array ( [0] => Array ( [0] => def [1] => 0 ) )
preg_match() は、pattern がマッチした回数を返します。つまり、0 回(マッチせず)または 1 回となります。 これは、最初にマッチした時点でpreg_match() は検索を止めるためです。逆にpreg_match_all()は、 subject の終わりまで検索を続けます。 preg_match() は、エラーが発生した場合にFALSEを返します。
ティップ: ある文字列が他の文字列内に含まれているかどうかを調べるためだけに preg_match() を使うのは避けた方が良いでしょう。 strpos() か strstr() 関数を 使う方が速くなります。
例 3. URL からドメイン名を得る
上の例の出力は以下となります。
|
preg_match_all(), preg_replace() および preg_split() も参照してください。