strspn()
Функция strspn() в PHP возвращает длину начального сегмента строки, состоящего только из символов, содержащихся в заданной маске.
Введение
Функция strspn() в PHP возвращает длину начального сегмента строки, состоящего исключительно из символов, входящих в заданную маску (набор допустимых символов). Как только функция встречает символ, которого нет в маске, она прекращает подсчёт и возвращает количество символов, совпавших до этой точки.
Простой способ думать об этом: «Начиная с начала, сколько символов принадлежат этому допустимому набору, пока не встретится символ, который ему не принадлежит?» Это делает strspn() удобным инструментом для лёгкой валидации и разбора строк — например, для проверки количества ведущих цифр в строке или для определения того, состоит ли значение только из разрешённых символов.
На этой странице рассматриваются синтаксис функции, каждый параметр (включая часто неправильно понимаемые $start и $length), несколько запускаемых примеров, типичные подводные камни и отличие от родственной функции strcspn().
Синтаксис
strspn(string $string, string $characters, int $offset = 0, ?int $length = null): int| Параметр | Описание |
|---|---|
$string | Исходная строка для анализа. |
$characters | Маска — набор символов, допустимых в начальном сегменте. Порядок символов не имеет значения. |
$offset | Необязательный. Позиция в $string, с которой начинается подсчёт. Отрицательное значение отсчитывается с конца строки. По умолчанию равно 0. |
$length | Необязательный. Максимальное количество символов для анализа. Отрицательное значение останавливает анализ за столько символов до конца строки. По умолчанию — остаток строки. |
Возвращаемое значение: int — длина начального совпадающего сегмента. Если первый анализируемый символ отсутствует в маске, возвращается 0.
Примечание: в официальном руководстве параметры называются
$stringи$characters. Их также можно встретить под именами subject и mask — это одно и то же.
Принцип работы
Функция сканирует $string слева направо (начиная с $offset) и ведёт текущий счётчик, пока каждый символ присутствует в $characters. Сканирование останавливается на первом символе, отсутствующем в маске, и этот счётчик возвращается. Функция никогда не просматривает строку дальше первого несовпадения, даже если последующие символы совпадают.
strspn() чувствительна к регистру и работает побайтово (обрабатывает одиночные байты, поэтому не поддерживает многобайтовые кодировки/UTF‑8).
Базовый пример
Строка "Hello" (5 символов) состоит исключительно из букв, входящих в маску "HeloWrd". Следующий символ — пробел, которого нет в маске, поэтому сканирование останавливается и функция возвращает 5. Обратите внимание, что маска должна лишь содержать допустимые буквы — символы W, r и d присутствуют в маске, хотя сканирование до них так и не доходит.
Подсчёт ведущих символов
Частый сценарий использования — определение количества ведущих символов определённого типа в начале строки, например ведущих цифр:
<?php
$digits = "1234567890";
echo strspn("42 is the answer", $digits); // 2
echo "\n";
echo strspn("abc123", $digits); // 0 — first char 'a' is not a digitПоскольку "42 is the answer" начинается двумя цифрами, за которыми следует пробел, результат равен 2. Во второй строке самый первый символ — буква, поэтому функция немедленно возвращает 0.
Использование $offset и $length
Необязательный параметр $offset позволяет начать подсчёт с произвольного места строки, а $length ограничивает количество анализируемых символов.
<?php
// Start at index 1 ("oobar"): 'o','o' match, 'b' stops -> 2
echo strspn("foobar", "of", 1); // 2
echo "\n";
// Only examine the first 1 character: 'f' matches -> 1
echo strspn("foobar", "f", 0, 1); // 1Отрицательный $offset отсчитывается с конца строки, а отрицательный $length останавливает анализ за столько символов до конца — это полезно, если нужно игнорировать завершающую часть строки.
Подводный камень с учётом регистра
strspn() различает верхний и нижний регистр. Если нужна проверка без учёта регистра, предварительно нормализуйте строку с помощью strtolower():
<?php
echo strspn("Hello", "helo"); // 0 — 'H' is not in the mask
echo "\n";
echo strspn(strtolower("Hello"), "helo"); // 4 — now 'hell' matchesstrspn() и strcspn()
Эти две функции являются зеркальным отображением друг друга:
strspn()подсчитывает ведущие символы, которые входят в маску.strcspn()подсчитывает ведущие символы, которые не входят в маску (останавливается на первом символе, который входит в маску).
Таким образом, strcspn("Hello World", " ") возвращает 5 — количество символов до первого пробела. Используйте strcspn(), когда нужно найти расстояние до первого «запрещённого» символа (например, разделителя). Подробнее см. strcspn().
Связанные функции
- strcspn() — дополнение; подсчитывает ведущие символы, не входящие в маску.
- strpos() — находит позицию первого вхождения подстроки.
- substr() — извлекает часть строки, часто используется вместе с
strspn()для вырезания совпавшего сегмента. - strlen() — возвращает общую длину строки.
Заключение
strspn() даёт точный ответ на вопрос: насколько длина последовательности допустимых символов в начале этой строки? Функция быстрая, не требует зависимостей и хорошо подходит для задач валидации и простого разбора строк. Помните, что она чувствительна к регистру и работает побайтово, останавливается на первом символе вне маски, а её аналог strcspn() выполняет обратную операцию. Зная эти правила, вы сможете писать лаконичные и эффективные проверки строк.