substr_count()
Функция substr_count() в PHP подсчитывает количество вхождений подстроки в строку. Узнайте о синтаксисе, параметрах и примерах использования.
Введение
Функция substr_count() в PHP подсчитывает, сколько раз подстрока встречается внутри более длинной строки. Она возвращает простое целое число, что делает её удобной для таких задач, как подсчёт частоты появления слова в тексте, подсчёт разделителей перед разбором значения или проверка того, что входная строка содержит ожидаемое количество разделителей.
В этой главе рассматриваются синтаксис функции, способ использования необязательных аргументов $offset и $length для сужения области поиска, два поведения, которые чаще всего вызывают путаницу (перекрывающиеся совпадения и чувствительность к регистру), а также практические ситуации, в которых стоит применять эту функцию.
Синтаксис
substr_count(string $haystack, string $needle, int $offset = 0, ?int $length = null): int| Параметр | Описание |
|---|---|
$haystack | Строка, в которой выполняется поиск. |
$needle | Подстрока для подсчёта. Должна содержать хотя бы один символ; пустая строка в $needle вызывает ValueError. |
$offset | Необязательный. Позиция в $haystack, с которой начинается поиск. Отрицательное смещение отсчитывается от конца строки. |
$length | Необязательный. Максимальное количество символов для поиска, начиная с $offset. Если не указан (или null), поиск выполняется до конца строки. |
Функция возвращает количество вхождений $needle в виде значения типа int.
Базовый пример
Здесь "is" встречается дважды — один раз в "This" и один раз в отдельном слове "is" — поэтому функция возвращает 2.
Ограничение поиска с помощью $offset и $length
Аргумент $offset указывает substr_count(), где начать поиск, а $length ограничивает его протяжённость. Это полезно, когда вас интересует только часть строки, например заголовочная секция или поле фиксированной ширины.
<?php
$text = "hello world hello";
// Start searching after the first word.
echo substr_count($text, "hello", 6), "\n"; // 1
// Search only the first 5 characters, starting at index 1.
echo substr_count("abcabcabc", "abc", 1, 5), "\n"; // 1В первом вызове поиск начинается с индекса 6, поэтому учитывается только второй "hello". Во втором вызове окно поиска — "bcabc" (5 символов, начиная с индекса 1), которое содержит ровно одно полное "abc".
Если
$offsetи$lengthвместе выходят за пределы строки, PHP выбрасываетValueError. Следите за тем, чтобы$offset + $lengthне превышалоstrlen($haystack).
Особенность: перекрывающиеся совпадения не учитываются
substr_count() не считает перекрывающиеся вхождения. Найдя совпадение, функция продолжает поиск с позиции, следующей за концом найденного совпадения, а не со следующего символа.
<?php
echo substr_count("aaa", "aa"); // 1, not 2В строке "aaa" есть два перекрывающихся вхождения "aa", но функция подсчитывает только первое и затем возобновляет поиск после него. Если вам нужны перекрывающиеся совпадения, используйте регулярное выражение с опережающим просмотром через preg_match_all().
Особенность: поиск чувствителен к регистру
substr_count() выполняет точное сравнение, поэтому "Apple" и "apple" — это разные подстроки.
<?php
$text = "Apple apple APPLE";
echo substr_count($text, "apple"), "\n"; // 1
// Normalize the case first for a case-insensitive count.
echo substr_count(strtolower($text), "apple"), "\n"; // 3Привести строку к нижнему регистру с помощью strtolower() перед подсчётом — самый простой способ сделать сравнение нечувствительным к регистру.
Когда использовать substr_count()
- Подсчёт разделителей — например, проверка количества запятых в строке CSV перед разбиением её с помощью
explode(). - Частота слов или токенов — измерение того, как часто термин встречается в блоке текста.
- Лёгкая валидация — проверка того, что значение содержит ожидаемое количество разделителей (например, ровно две точки в строке версии).
Когда вам нужна позиция совпадения, а не его количество, используйте strpos(); когда нужно извлечь часть строки — substr().
Заключение
substr_count() — быстрый и простой способ подсчитать вхождения подстроки и вернуть результат в виде целого числа. Помните о двух ключевых особенностях функции: она не учитывает перекрывающиеся совпадения и чувствительна к регистру. Используйте аргументы $offset и $length, чтобы ограничить область поиска, когда вам нужно проверить только часть строки.