【PHP8.x】strcspn関数の使い方

strcspn関数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年09月29日

基本的な使い方

strcspn関数は、検索対象の文字列 ($haystack) の中で、指定された文字セット ($characters) に含まれる文字が最初に出現するまでの長さを、バイト単位で計測して返す関数です。

この関数は、検索対象の文字列を$haystack、検索したい文字の集合を$charactersとして受け取ります。$haystackの先頭から検索を開始し、$characters内のいずれかの文字が最初に見つかるまでのバイト数を整数値として返します。例えば、「HelloWorld」という文字列に対して「oW」という文字セットを指定すると、「4」を返します。

オプションとして$offset引数を使用すると、$haystackの指定したバイト位置から検索を開始できます。さらに$length引数を指定すると、$offsetから数えて指定されたバイト数分の範囲内でのみ検索を実行することも可能です。

この関数の戻り値はバイト単位であるため、日本語などのマルチバイト文字を扱う際には注意が必要です。文字数とバイト数が異なる場合があるため、意図しない結果を避けるには、使用する文字エンコーディングに留意し、正確な文字列処理に活用してください。

構文(syntax)


1<?php
2$textString = "example.com";
3$charactersToFind = ".0123456789";
4
5// $textString の先頭から、$charactersToFind に含まれる文字が最初に出現するまでの長さを計算します。
6// この例では、'.' が $charactersToFind に含まれるため、'e', 'x', 'a', 'm', 'p', 'l', 'e' の7文字の後に'.'が来るので、7が返されます。
7$lengthBeforeMatch = strcspn($textString, $charactersToFind);
8
9echo $lengthBeforeMatch;
10?>

引数(parameters)

string $string, string $characters, int $offset = 0, ?int $length = null

string $string: 検索対象の文字列
string $characters: 検索する文字のセットを指定する文字列
int $offset = 0: 検索を開始する $string の位置
?int $length = null: $string の検索範囲の最大長

戻り値(return)

int

指定された文字列から、指定された文字集合に含まれる文字が最初に出現するまでの文字数を返します。

サンプルコード

strcspn関数で指定文字セット外の文字までの長さを取得する


1<?php
2
3/**
4 * strcspn 関数のサンプルコード
5 *
6 * @param string $string 検索対象の文字列
7 * @param string $characters 検索する文字セット
8 * @param int $offset 開始位置
9 * @param int|null $length 長さ
10 * @return int
11 */
12function strcspn_example(string $string, string $characters, int $offset = 0, ?int $length = null): int
13{
14    // strcspn 関数を使用して、指定された文字セットに含まれない文字が最初に現れるまでの文字列の長さを取得します。
15    $result = strcspn($string, $characters, $offset, $length);
16
17    return $result;
18}
19
20// 関数の使用例
21$string = "Hello, world!";
22$characters = ", "; // カンマとスペース
23$offset = 0;
24$length = 5;
25
26$length_before_match = strcspn_example($string, $characters, $offset, $length);
27
28echo "文字列 '$string' で '$characters' に含まれない文字が最初に現れるまでの長さ (offset=$offset, length=$length): " . $length_before_match . PHP_EOL; // 出力: 5
29
30$length_before_match = strcspn_example($string, $characters);
31echo "文字列 '$string' で '$characters' に含まれない文字が最初に現れるまでの長さ (offset=0, length=null): " . $length_before_match . PHP_EOL; // 出力: 5

strcspn関数は、PHPで文字列の中から特定の文字セットに含まれない文字が最初に現れるまでの長さを調べるために使用されます。この関数は、検索対象の文字列$string、検索する文字セット$characters、検索開始位置を示すオプションの引数$offset、および検索する長さを指定するオプションの引数$lengthを受け取ります。

$stringは検索対象となる文字列です。$charactersは検索する文字セットを文字列で指定します。$offsetは検索を開始する位置を整数で指定します。省略した場合は0から検索します。$lengthは検索する長さを整数で指定します。省略した場合は文字列の最後まで検索します。

サンプルコードでは、strcspn_example関数内でstrcspn関数を使用し、その結果を返しています。strcspn関数は、$stringの中から$charactersに含まれる文字が現れるまでの長さを整数で返します。例えば、$stringが"Hello, world!"で$charactersが", "（カンマとスペース）の場合、strcspn関数は最初のカンマまでの長さである5を返します。

offsetとlengthを調整することで、文字列の特定の部分に対して検索を行うことができます。strcspn関数は、文字列の解析や検証に役立ちます。

strcspn関数は、文字列$stringの中で、指定された文字セット$charactersに含まれる文字が最初に現れるまでの長さを返します。$offsetで検索開始位置を指定でき、$lengthで検索する長さを制限できます。$lengthにnullを指定すると、$offsetから文字列の最後までが検索対象となります。$offsetと$lengthを適切に設定しないと、意図しない結果になる可能性があります。$charactersには、検索したい文字をすべて含める必要があります。文字セットに含まれない文字が見つからない場合、$lengthが指定されていれば$lengthが、そうでなければ文字列の長さが返されます。引数の型を間違えないように注意してください。