strcspn()

Introduction

La fonction strcspn() en PHP retourne la longueur du segment initial d'une chaîne ne contenant aucun des caractères listés dans une seconde chaîne. En d'autres termes, elle compte combien de caractères au début d'une chaîne peuvent être lus avant de rencontrer un caractère « stop ». Cette page explique la syntaxe, les paramètres optionnels $start et $length, le comportement de la fonction dans les cas limites, et comment elle diffère de sa fonction complémentaire strspn().

Le nom se lit comme « string complement span » (étendue du complément de chaîne) : elle couvre la partie de la chaîne qui ne correspond pas à l'ensemble de caractères donné. Les utilisations courantes incluent la recherche de la longueur d'un token avant un délimiteur, la validation qu'un préfixe ne contient pas de caractères interdits, et l'analyse légère sans expression régulière.

Syntaxe

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

La fonction retourne un int : le nombre de caractères en tête (dans la fenêtre balayée) qui ne sont pas présents dans $characters. Si le tout premier caractère est dans l'ensemble, elle retourne 0.

Remarque : strcspn() fonctionne sur les octets, pas sur les caractères multi-octets. Pour les chaînes UTF-8 avec des caractères non-ASCII, préférez une expression régulière (preg_match) à la place.

Exemple de base

Ici, nous balayons "Hello World" pour la première occurrence de o ou e. En partant du début, H est sûr, mais le caractère suivant e est dans l'ensemble, donc le segment initial sûr est juste "H" et la fonction retourne 1.

Quand aucun caractère stop n'est présent

Si aucun des caractères de $characters n'apparaît dans la portion balayée, la fonction retourne la longueur totale de cette portion :

<?php

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

C'est pratique pour vérifier si un préfixe évite entièrement un ensemble de caractères — si la valeur retournée est égale à la longueur de la chaîne, la chaîne est propre.

Exemple pratique : lire un token jusqu'à un délimiteur

Une utilisation fréquente dans le monde réel est de mesurer combien de caractères apparaissent avant un délimiteur. Le nombre retourné par strcspn() est exactement la longueur que vous pouvez passer à substr() pour extraire le token en tête :

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

Le premier chiffre (1) apparaît à l'index 7, donc le préfixe non numérique "price: " fait 7 caractères. Nous découpons ensuite ce préfixe avec substr().

Utilisation de $start et $length

Les paramètres optionnels $offset et $length limitent le balayage à une fenêtre de la chaîne :

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

Dans le premier appel, le balayage commence à l'offset 6, où la sous-chaîne est "World" ; son premier caractère W est dans l'ensemble stop, donc le résultat est 0. Dans le second appel, la fenêtre est limitée à "Hello", et le premier l se trouve à l'index 2, donc le résultat est 2.

strcspn() vs strspn()

Ces deux fonctions sont des images miroir l'une de l'autre :

• strspn() compte les caractères en tête qui sont dans l'ensemble de caractères (l'étendue correspond).
• strcspn() compte les caractères en tête qui ne sont pas dans l'ensemble (l'étendue complémentaire).

Utilisez strspn() lorsque vous avez une liste d'autorisation (« quelle est la longueur de la suite de caractères valides ? ») et strcspn() lorsque vous avez une liste d'interdiction (« jusqu'où peut-on aller avant de toucher un caractère interdit ? »).

Fonctions associées

• strpos() — trouver la position d'une seule sous-chaîne plutôt que n'importe quel caractère d'un ensemble.
• strstr() — retourner la partie d'une chaîne à partir de la première correspondance.
• strlen() — obtenir la longueur totale d'une chaîne.
• strtok() — diviser une chaîne en tokens par un ensemble de délimiteurs.

Conclusion

strcspn() est un moyen rapide, sans expression régulière, de mesurer combien de caractères au début d'une chaîne sont exempts d'un ensemble donné. Comme elle retourne une longueur, elle s'associe naturellement à substr() pour extraire des tokens en tête, et elle complète strspn() pour le balayage de type liste d'autorisation. Rappelez-vous qu'elle opère sur les octets, donc utilisez preg_match() lorsque vous avez besoin d'une correspondance tenant compte des caractères multi-octets.

Pratique