strspn()

Introducción

La función strspn() en PHP devuelve la longitud del segmento inicial de una cadena que consiste íntegramente en caracteres encontrados en una máscara dada (un conjunto de caracteres permitidos). En cuanto encuentra un carácter que no está en la máscara, deja de contar y devuelve cuántos caracteres coincidieron antes de ese punto.

Una forma habitual de pensarlo: "Comenzando desde el principio, ¿cuántos caracteres pertenecen a este conjunto permitido antes de encontrar uno que no pertenezca?" Esto hace que strspn() sea útil para validaciones ligeras y análisis sintáctico — por ejemplo, comprobar cuántos dígitos iniciales tiene una cadena, o si un valor está compuesto únicamente por caracteres permitidos.

Esta página cubre la sintaxis de la función, cada parámetro (incluidos los frecuentemente mal entendidos $start y $length), varios ejemplos ejecutables, errores comunes y cómo se relaciona con su contraparte strcspn().

Sintaxis

strspn(string $string, string $characters, int $offset = 0, ?int $length = null): int

Valor de retorno: un int — la longitud del segmento inicial coincidente. Si el primer carácter examinado no está en la máscara, devuelve 0.

Nota: en el manual oficial los parámetros se denominan $string y $characters. También pueden aparecer como subject y mask — significan lo mismo.

Cómo funciona

La función recorre $string de izquierda a derecha (comenzando en $offset) y mantiene un contador mientras cada carácter esté presente en $characters. El recorrido se detiene en el primer carácter que no está en la máscara, y ese contador se devuelve. Nunca mira más allá de la primera discrepancia, incluso si los caracteres posteriores habrían coincidido.

strspn() distingue mayúsculas de minúsculas y opera por bytes (trabaja con bytes individuales, por lo que no es compatible con multibyte/UTF‑8).

Ejemplo básico

"Hello" (5 caracteres) está formado íntegramente por letras de la máscara "HeloWrd". El siguiente carácter es un espacio, que no está en la máscara, por lo que el recorrido se detiene y la función devuelve 5. Nótese que la máscara solo necesita contener las letras permitidas — la W, r y d están presentes aunque el recorrido nunca llegue a ellas.

Contar caracteres iniciales

Un caso de uso frecuente es medir cuántos caracteres iniciales de un determinado tipo tiene una cadena — por ejemplo, dígitos iniciales:

<?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

Como "42 is the answer" comienza con dos dígitos seguidos de un espacio, el resultado es 2. En la segunda cadena el primer carácter es una letra, por lo que la función devuelve 0 de inmediato.

Usando $offset y $length

El parámetro opcional $offset permite comenzar a contar desde un punto intermedio de la cadena, y $length limita cuántos caracteres se examinan.

<?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

Un $offset negativo cuenta desde el final de la cadena, y un $length negativo se detiene tantos caracteres antes del final — útil cuando se desea ignorar una parte final.

Error común con la distinción de mayúsculas

strspn() distingue mayúsculas de minúsculas. Si necesitas una comprobación sin distinción de mayúsculas, normaliza primero la cadena con strtolower():

<?php

echo strspn("Hello", "helo");                  // 0 — 'H' is not in the mask
echo "\n";
echo strspn(strtolower("Hello"), "helo");      // 4 — now 'hell' matches

strspn() vs strcspn()

Las dos funciones son imágenes especulares una de la otra:

• strspn() cuenta los caracteres iniciales que están en la máscara.
• strcspn() cuenta los caracteres iniciales que no están en la máscara (se detiene en el primer carácter que sí está en la máscara).

Así, strcspn("Hello World", " ") devuelve 5 — el número de caracteres antes del primer espacio. Recurre a strcspn() cuando quieras saber a qué distancia está el primer carácter "prohibido" (como un delimitador). Consulta strcspn() para más detalles.

Funciones relacionadas

• strcspn() — la complementaria; cuenta los caracteres iniciales que no están en la máscara.
• strpos() — encuentra la posición de la primera aparición de una subcadena.
• substr() — extrae parte de una cadena, frecuentemente combinada con strspn() para separar el segmento coincidente.
• strlen() — obtiene la longitud total de una cadena.

Conclusión

strspn() responde a una pregunta precisa: ¿qué longitud tiene la secuencia de caracteres permitidos al inicio de esta cadena? Es rápida, sin dependencias externas y muy adecuada para tareas de validación y análisis sintáctico simple. Recuerda que distingue mayúsculas de minúsculas y opera por bytes, que se detiene en el primer carácter fuera de la máscara, y que su contraparte strcspn() hace lo inverso. Con estas reglas en mente puedes utilizarla para escribir comprobaciones de cadenas concisas y eficientes.

Práctica