strcspn()

Introducción

La función strcspn() en PHP devuelve la longitud del segmento inicial de una cadena que no contiene ninguno de los caracteres listados en una segunda cadena. En otras palabras, cuenta cuántos caracteres al inicio de una cadena se pueden leer antes de encontrar algún carácter "de parada". Esta página explica la sintaxis, los parámetros opcionales $start y $length, el comportamiento de la función en casos límite y cómo se diferencia de su función complementaria strspn().

El nombre se lee como "string complement span": abarca la parte de la cadena que no coincide con el conjunto de caracteres dado. Los usos más comunes incluyen encontrar hasta dónde llega un token antes de un delimitador, validar que un prefijo no contiene caracteres prohibidos y realizar análisis ligero sin expresiones regulares.

Sintaxis

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

La función devuelve un int: el número de caracteres iniciales (dentro de la ventana analizada) que no están presentes en $characters. Si el primer carácter pertenece al conjunto, devuelve 0.

Nota: strcspn() opera sobre bytes, no sobre caracteres multibyte. Para cadenas UTF-8 con caracteres no ASCII, es preferible usar una expresión regular (preg_match).

Ejemplo básico

Aquí analizamos "Hello World" en busca de la primera aparición de o o e. Leyendo desde el inicio, H es seguro, pero el siguiente carácter e está en el conjunto, por lo que el segmento inicial seguro es solo "H" y la función devuelve 1.

Cuando no hay ningún carácter de parada

Si ninguno de los caracteres en $characters aparece en la porción analizada, la función devuelve la longitud completa de dicha porción:

<?php

echo strcspn("abcd", "xyz"); // 4 — none of x, y, z occur, so the whole string qualifies

Esto es útil para preguntar "¿este prefijo evita completamente un conjunto de caracteres?" — si el valor devuelto es igual a la longitud de la cadena, la cadena está limpia.

Un ejemplo práctico: leer un token hasta un delimitador

Un uso frecuente en el mundo real es medir cuántos caracteres aparecen antes de un delimitador. El número que devuelve strcspn() es exactamente la longitud que se puede pasar a substr() para extraer el token inicial:

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

El primer dígito (1) aparece en el índice 7, por lo que el prefijo no numérico "price: " tiene 7 caracteres de longitud. Luego extraemos ese prefijo con substr().

Uso de $start y $length

Los parámetros opcionales $offset y $length restringen el análisis a una ventana de la cadena:

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

En la primera llamada, el análisis comienza en el offset 6, donde la subcadena es "World"; su primer carácter W está en el conjunto de parada, por lo que el resultado es 0. En la segunda llamada, la ventana se limita a "Hello", y la primera l está en el índice 2, por lo que el resultado es 2.

strcspn() vs strspn()

Estas dos funciones son imágenes especulares:

• strspn() cuenta los caracteres iniciales que están en el conjunto de caracteres (la extensión que coincide).
• strcspn() cuenta los caracteres iniciales que no están en el conjunto (la extensión complementaria).

Use strspn() cuando tenga una lista de permitidos ("¿qué tan larga es la secuencia de caracteres válidos?") y strcspn() cuando tenga una lista de parada ("¿hasta dónde llego antes de encontrar un carácter prohibido?").

Funciones relacionadas

• strpos() — encuentra la posición de una subcadena concreta en lugar de cualquiera de un conjunto de caracteres.
• strstr() — devuelve la parte de una cadena desde la primera coincidencia en adelante.
• strlen() — obtiene la longitud total de una cadena.
• strtok() — divide una cadena en tokens mediante un conjunto de delimitadores.

Conclusión

strcspn() es una forma rápida y sin expresiones regulares de medir cuántos caracteres al inicio de una cadena están libres de un conjunto dado. Como devuelve una longitud, se combina naturalmente con substr() para extraer tokens iniciales, y complementa a strspn() para el análisis con listas de permitidos. Recuerde que opera sobre bytes, así que recurra a preg_match() cuando necesite coincidencias compatibles con multibyte.

Práctica