strcspn()

Introdução

A função strcspn() no PHP retorna o comprimento do segmento inicial de uma string que não contém nenhum dos caracteres listados em uma segunda string. Em outras palavras, ela conta quantos caracteres no início de uma string podem ser lidos antes de encontrar algum caractere de "parada". Esta página explica a sintaxe, os parâmetros opcionais $start e $length, o comportamento da função em casos extremos e como ela difere de sua função complementar strspn().

O nome pode ser lido como "string complement span": ela percorre a parte da string que não corresponde ao conjunto de caracteres fornecido. Usos comuns incluem descobrir até onde um token vai antes de um delimitador, validar que um prefixo está livre de caracteres proibidos e fazer análise leve sem uma expressão regular.

Sintaxe

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

A função retorna um int: o número de caracteres iniciais (dentro da janela varrida) que não estão presentes em $characters. Se o primeiro caractere estiver no conjunto, o retorno será 0.

Nota: strcspn() opera em bytes, não em caracteres multibyte. Para strings UTF-8 com caracteres não ASCII, prefira uma expressão regular (preg_match).

Exemplo básico

Aqui varremos "Hello World" em busca da primeira ocorrência de o ou e. Lendo a partir do início, H é seguro, mas o próximo caractere e está no conjunto, então o segmento inicial seguro é apenas "H" e a função retorna 1.

Quando nenhum caractere de parada está presente

Se nenhum dos caracteres em $characters aparecer na parte varrida, a função retorna o comprimento completo dessa parte:

<?php

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

Isso é útil para perguntar "este prefixo evita completamente um conjunto de caracteres?" — se o valor retornado for igual ao comprimento da string, a string está limpa.

Um exemplo prático: lendo um token até um delimitador

Um uso real frequente é medir quantos caracteres aparecem antes de um delimitador. O número retornado por strcspn() é exatamente o comprimento que pode ser passado para substr() para extrair o 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:

O primeiro dígito (1) aparece no índice 7, então o prefixo não numérico "price: " tem 7 caracteres. Em seguida, extraímos esse prefixo com substr().

Usando $start e $length

Os parâmetros opcionais $offset e $length restringem a varredura a uma janela da string:

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

Na primeira chamada, a varredura começa no offset 6, onde a substring é "World"; seu primeiro caractere W está no conjunto de parada, então o resultado é 0. Na segunda chamada, a janela é limitada a "Hello", e o primeiro l está no índice 2, então o resultado é 2.

strcspn() vs strspn()

Essas duas funções são imagens espelhadas:

• strspn() conta os caracteres iniciais que estão no conjunto de caracteres (o span corresponde).
• strcspn() conta os caracteres iniciais que não estão no conjunto (o span complementar).

Use strspn() quando você tem uma lista de permissões ("qual é o comprimento da sequência de caracteres válidos?") e strcspn() quando você tem uma lista de parada ("até onde até encontrar um caractere proibido?").

Funções relacionadas

• strpos() — encontra a posição de uma única substring em vez de qualquer caractere de um conjunto.
• strstr() — retorna a parte de uma string a partir da primeira correspondência.
• strlen() — obtém o comprimento total de uma string.
• strtok() — divide uma string em tokens por um conjunto de delimitadores.

Conclusão

strcspn() é uma maneira rápida e sem expressões regulares de medir quantos caracteres no início de uma string estão livres de um dado conjunto. Como retorna um comprimento, combina naturalmente com substr() para extrair tokens iniciais e complementa strspn() para varreduras no estilo de lista de permissões. Lembre-se de que opera em bytes, então recorra a preg_match() quando precisar de correspondência com suporte a multibyte.

Prática