strcspn()

Introduzione

La funzione strcspn() in PHP restituisce la lunghezza del segmento iniziale di una stringa che non contiene nessuno dei caratteri elencati in una seconda stringa. In altre parole, conta quanti caratteri all'inizio di una stringa si possono leggere prima di incontrare un carattere di "stop". Questa pagina illustra la sintassi, i parametri facoltativi $start e $length, il comportamento della funzione nei casi limite e come si differenzia dalla sua funzione complementare strspn().

Il nome si legge come "string complement span": si estende sulla parte della stringa che non corrisponde all'insieme di caratteri specificato. Gli utilizzi più comuni includono trovare la lunghezza di un token prima di un delimitatore, verificare che un prefisso sia privo di caratteri vietati e il parsing leggero senza espressioni regolari.

Sintassi

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

La funzione restituisce un int: il numero di caratteri iniziali (all'interno della finestra scansionata) che non sono presenti in $characters. Se il primo carattere fa parte dell'insieme, restituisce 0.

Nota: strcspn() opera sui byte, non sui caratteri multibyte. Per le stringhe UTF-8 con caratteri non ASCII, è preferibile utilizzare un'espressione regolare (preg_match).

Esempio di base

Qui scansionamo "Hello World" cercando la prima occorrenza di o o e. Partendo dall'inizio, H è sicuro, ma il carattere successivo e è nell'insieme, quindi il segmento iniziale sicuro è solo "H" e la funzione restituisce 1.

Quando nessun carattere di stop è presente

Se nessuno dei caratteri in $characters compare nella porzione scansionata, la funzione restituisce la lunghezza totale di quella porzione:

<?php

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

Questo è utile per verificare se un prefisso evita completamente un insieme di caratteri — se il valore restituito è uguale alla lunghezza della stringa, la stringa è pulita.

Un esempio pratico: leggere un token fino a un delimitatore

Un utilizzo frequente nel mondo reale è misurare quanti caratteri compaiono prima di un delimitatore. Il numero restituito da strcspn() è esattamente la lunghezza che si può passare a substr() per estrarre il token iniziale:

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

La prima cifra (1) appare all'indice 7, quindi il prefisso non numerico "price: " è lungo 7 caratteri. Poi estraiamo quel prefisso con substr().

Utilizzo di $start e $length

I parametri facoltativi $offset e $length limitano la scansione a una finestra della stringa:

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

Nella prima chiamata la scansione inizia all'offset 6, dove la sottostringa è "World"; il suo primo carattere W è nell'insieme di stop, quindi il risultato è 0. Nella seconda chiamata la finestra è limitata a "Hello", e la prima l si trova all'indice 2, quindi il risultato è 2.

strcspn() vs strspn()

Queste due funzioni sono immagini speculari:

• strspn() conta i caratteri iniziali che sono nell'insieme di caratteri (la porzione corrisponde).
• strcspn() conta i caratteri iniziali che non sono nell'insieme (la porzione complementare).

Usa strspn() quando hai una lista di caratteri consentiti ("quanto dura la sequenza di caratteri validi?") e strcspn() quando hai una lista di caratteri di stop ("quanto manca prima di incontrare un carattere vietato?").

Funzioni correlate

• strpos() — trova la posizione di una singola sottostringa invece che qualsiasi carattere di un insieme.
• strstr() — restituisce la parte di una stringa a partire dalla prima corrispondenza.
• strlen() — ottiene la lunghezza totale di una stringa.
• strtok() — divide una stringa in token usando un insieme di delimitatori.

Conclusione

strcspn() è un metodo rapido, senza espressioni regolari, per misurare quanti caratteri all'inizio di una stringa sono privi di un dato insieme. Poiché restituisce una lunghezza, si abbina naturalmente a substr() per estrarre token iniziali, e complementa strspn() per la scansione con lista di caratteri consentiti. Ricorda che opera sui byte, quindi usa preg_match() quando hai bisogno di corrispondenza con supporto multibyte.

Esercizio