strcspn()
Функция strcspn() в PHP возвращает длину начального сегмента строки, не содержащего символов из заданного набора.
Введение
Функция strcspn() в PHP возвращает длину начального сегмента строки, который не содержит ни одного из символов, перечисленных во второй строке. Иначе говоря, она считает, сколько символов с начала строки можно прочитать до встречи любого «стоп-символа». На этой странице рассматриваются синтаксис, необязательные параметры $start и $length, поведение функции в граничных случаях, а также её отличие от функции-«близнеца» strspn().
Название читается как «string complement span» («дополнительный диапазон строки»): функция охватывает ту часть строки, которая не соответствует заданному набору символов. Типичные сценарии использования: определение длины токена до разделителя, проверка того, что префикс не содержит запрещённых символов, и лёгкий синтаксический разбор без регулярных выражений.
Синтаксис
strcspn(string $string, string $characters, int $offset = 0, ?int $length = null): int| Параметр | Описание |
|---|---|
$string | Проверяемая строка. |
$characters | Набор «стоп-символов». Порядок и повторение символов здесь не имеют значения — важно лишь принадлежность символа к набору. |
$offset | Позиция, с которой начинается сканирование. Положительное значение отсчитывается от начала; отрицательное — от конца строки. По умолчанию равно 0. |
$length | Количество символов для сканирования начиная с $offset. Отрицательное значение означает сканирование до стольких символов от конца строки. По умолчанию сканирование продолжается до конца. |
Функция возвращает int — количество начальных символов (в пределах окна сканирования), которые отсутствуют в $characters. Если самый первый символ входит в набор, функция возвращает 0.
Примечание:
strcspn()работает с байтами, а не с многобайтовыми символами. Для UTF-8 строк с символами не из ASCII предпочтительнее использовать регулярное выражение (preg_match).
Базовый пример
Здесь мы ищем в строке "Hello World" первое вхождение символа o или e. Читая с начала, H безопасен, но следующий символ e входит в набор, поэтому безопасный начальный сегмент — только "H", и функция возвращает 1.
Когда стоп-символ не встречается
Если ни один из символов $characters не встречается в сканируемой части, функция возвращает полную длину этой части:
<?php
echo strcspn("abcd", "xyz"); // 4 — none of x, y, z occur, so the whole string qualifiesЭто удобно для проверки «не содержит ли этот префикс ни одного из заданных символов?» — если возвращаемое значение равно длине строки, строка «чистая».
Практический пример: чтение токена до разделителя
Частый сценарий — измерение количества символов, стоящих перед разделителем. Число, возвращаемое strcspn(), — это ровно та длина, которую можно передать в substr() для извлечения ведущего токена:
<?php
$line = "price: 100USD";
$digits = "0123456789";
$prefixLength = strcspn($line, $digits); // 7 — "price: " before the first digit
$label = substr($line, 0, $prefixLength);
echo $prefixLength; // 7
echo "\n";
echo $label; // price:Первая цифра (1) встречается на позиции 7, поэтому нецифровой префикс "price: " имеет длину 7 символов. Затем мы извлекаем этот префикс с помощью substr().
Использование $start и $length
Необязательные параметры $offset и $length ограничивают сканирование определённым окном строки:
<?php
// Start scanning at index 6 ("World"); 'W' is itself a stop character → 0
echo strcspn("Hello World", "World", 6); // 0
echo "\n";
// Scan only the first 5 characters ("Hello") for 'l' or 'd' → stops at the first 'l'
echo strcspn("Hello World", "ld", 0, 5); // 2В первом вызове сканирование начинается с позиции 6, где подстрока — "World"; её первый символ W входит в набор стоп-символов, поэтому результат равен 0. Во втором вызове окно ограничено строкой "Hello", и первый символ l находится на позиции 2, поэтому результат равен 2.
strcspn() и strspn()
Эти две функции являются зеркальными отображениями друг друга:
strspn()считает начальные символы, которые входят в набор символов (диапазон совпадает).strcspn()считает начальные символы, которые не входят в набор (диапазон дополнения).
Используйте strspn(), когда у вас есть список разрешённых символов («насколько длинна серия допустимых символов?»), и strcspn(), когда у вас есть список стоп-символов («как далеко до запрещённого символа?»).
Связанные функции
strpos()— найти позицию одной подстроки, а не любого символа из набора.strstr()— вернуть часть строки начиная с первого совпадения.strlen()— получить полную длину строки.strtok()— разбить строку на токены по набору разделителей.
Заключение
strcspn() — это быстрый способ без регулярных выражений измерить, сколько символов в начале строки свободны от заданного набора. Поскольку функция возвращает длину, она естественно сочетается с substr() для извлечения ведущих токенов и дополняет strspn() при сканировании по списку разрешённых символов. Помните, что функция работает с байтами, поэтому для многобайтового сравнения используйте preg_match().