strspn()

Introduction

La fonction strspn() en PHP retourne la longueur du segment initial d'une chaîne composé entièrement de caractères présents dans un masque donné (un ensemble de caractères autorisés). Dès qu'elle rencontre un caractère qui n'est pas dans le masque, elle cesse de compter et retourne le nombre de caractères correspondants avant ce point.

Une façon courante de l'envisager : "En partant du début, combien de caractères appartiennent à cet ensemble autorisé avant d'en rencontrer un qui n'y est pas ?" Cela rend strspn() pratique pour la validation légère et l'analyse syntaxique — par exemple, vérifier combien de chiffres initiaux contient une chaîne, ou si une valeur est composée uniquement de caractères autorisés.

Cette page couvre la syntaxe de la fonction, chaque paramètre (y compris les souvent mal compris $start et $length), plusieurs exemples exécutables, les pièges courants, et sa relation avec sa fonction homologue strcspn().

Syntaxe

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

Valeur de retour : un int — la longueur du segment correspondant initial. Si le tout premier caractère examiné n'est pas dans le masque, la fonction retourne 0.

Remarque : dans le manuel officiel, les paramètres sont nommés $string et $characters. Vous pouvez aussi les voir appelés subject et mask — ils désignent la même chose.

Fonctionnement

La fonction parcourt $string de gauche à droite (en commençant à $offset) et maintient un compteur tant que chaque caractère est présent dans $characters. Le parcours s'arrête au premier caractère qui n'est pas dans le masque, et ce compteur est retourné. Elle ne regarde jamais au-delà du premier caractère non correspondant, même si des caractères ultérieurs auraient correspondu.

strspn() est sensible à la casse et basée sur les octets (elle opère sur des octets simples, donc elle n'est pas compatible avec le multioctet/UTF‑8).

Exemple de base

"Hello" (5 caractères) est entièrement composé de lettres présentes dans le masque "HeloWrd". Le caractère suivant est une espace, qui n'est pas dans le masque, donc le parcours s'arrête et la fonction retourne 5. Notez que le masque doit seulement contenir les lettres autorisées — le W, r et d sont présents même si le parcours ne les atteint jamais.

Compter les caractères initiaux

Un cas d'utilisation fréquent est de mesurer combien de caractères d'un certain type se trouvent au début d'une chaîne — par exemple, des chiffres initiaux :

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

Comme "42 is the answer" commence par deux chiffres suivis d'une espace, le résultat est 2. Dans la seconde chaîne, le tout premier caractère est une lettre, donc la fonction retourne 0 immédiatement.

Utiliser $offset et $length

Le paramètre optionnel $offset permet de commencer le comptage à mi-chemin dans la chaîne, et $length limite le nombre de caractères examinés.

<?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 négatif compte depuis la fin de la chaîne, et un $length négatif s'arrête à autant de caractères avant la fin — utile lorsque vous souhaitez ignorer une partie finale.

Piège de la sensibilité à la casse

strspn() distingue les majuscules et les minuscules. Si vous avez besoin d'une vérification insensible à la casse, normalisez d'abord la chaîne avec 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()

Les deux fonctions sont le miroir l'une de l'autre :

• strspn() compte les caractères initiaux qui sont dans le masque.
• strcspn() compte les caractères initiaux qui ne sont pas dans le masque (elle s'arrête au premier caractère qui est dans le masque).

Ainsi strcspn("Hello World", " ") retourne 5 — le nombre de caractères avant la première espace. Utilisez strcspn() lorsque vous souhaitez savoir jusqu'où se trouve le premier caractère "interdit" (comme un délimiteur). Voir strcspn() pour les détails.

Fonctions associées

• strcspn() — la fonction complémentaire ; compte les caractères initiaux non présents dans le masque.
• strpos() — trouver la position de la première occurrence d'une sous-chaîne.
• substr() — extraire une partie d'une chaîne, souvent combinée avec strspn() pour découper le segment correspondant.
• strlen() — obtenir la longueur totale d'une chaîne.

Conclusion

strspn() répond à une question précise : quelle est la longueur de la séquence de caractères autorisés au début de cette chaîne ? Elle est rapide, sans dépendance, et bien adaptée aux tâches de validation et d'analyse syntaxique simple. N'oubliez pas qu'elle est sensible à la casse et basée sur les octets, qu'elle s'arrête au premier caractère hors du masque, et que sa fonction homologue strcspn() fait l'inverse. En gardant ces règles à l'esprit, vous pouvez l'utiliser pour écrire des vérifications de chaînes concises et efficaces.

Pratique