strspn()

Introdução

A função strspn() no PHP retorna o comprimento do segmento inicial de uma string que consiste inteiramente de caracteres encontrados em uma dada máscara (um conjunto de caracteres permitidos). Assim que encontra um caractere que não está na máscara, ela para de contar e retorna quantos caracteres corresponderam antes desse ponto.

Uma forma comum de pensar sobre isso: "Começando do início, quantos caracteres pertencem a esse conjunto permitido antes de eu encontrar um que não pertence?" Isso torna o strspn() útil para validação e análise simples — por exemplo, verificar quantos dígitos iniciais uma string possui, ou se um valor é composto apenas de caracteres permitidos.

Esta página abrange a sintaxe da função, cada parâmetro (incluindo os frequentemente incompreendidos $start e $length), vários exemplos executáveis, armadilhas comuns e como ela se relaciona com sua contraparte strcspn().

Sintaxe

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

Valor de retorno: um int — o comprimento do segmento inicial correspondente. Se o primeiro caractere examinado não estiver na máscara, retorna 0.

Nota: no manual oficial, os parâmetros são chamados de $string e $characters. Você também pode vê-los chamados de subject e mask — significam a mesma coisa.

Como funciona

A função percorre $string da esquerda para a direita (começando em $offset) e mantém uma contagem enquanto cada caractere estiver presente em $characters. A varredura para no primeiro caractere que não está na máscara, e essa contagem é retornada. Ela nunca olha além da primeira incompatibilidade, mesmo que caracteres posteriores correspondessem.

strspn() é sensível a maiúsculas e minúsculas e baseada em bytes (trabalha com bytes individuais, portanto não é compatível com multibyte/UTF‑8).

Exemplo básico

"Hello" (5 caracteres) é composto inteiramente de letras presentes na máscara "HeloWrd". O próximo caractere é um espaço, que não está na máscara, então a varredura para e a função retorna 5. Note que a máscara só precisa conter as letras permitidas — o W, r e d estão presentes mesmo que a varredura nunca os alcance.

Contando caracteres iniciais

Um caso de uso frequente é medir quantos caracteres iniciais de um determinado tipo uma string começa — por exemplo, dígitos iniciais:

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

Como "42 is the answer" começa com dois dígitos seguidos de um espaço, o resultado é 2. Na segunda string, o primeiro caractere é uma letra, então a função retorna 0 imediatamente.

Usando $offset e $length

O $offset opcional permite começar a contar no meio da string, e $length limita quantos caracteres são examinados.

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

Um $offset negativo conta a partir do final da string, e um $length negativo para essa quantidade de caracteres antes do final — útil quando você quer ignorar uma parte final.

Armadilha de sensibilidade a maiúsculas e minúsculas

strspn() diferencia maiúsculas de minúsculas. Se você precisar de uma verificação sem distinção de maiúsculas e minúsculas, normalize a string primeiro com 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()

As duas funções são imagens espelhadas uma da outra:

• strspn() conta os caracteres iniciais que estão na máscara.
• strcspn() conta os caracteres iniciais que não estão na máscara (ela para no primeiro caractere que está na máscara).

Portanto, strcspn("Hello World", " ") retorna 5 — o número de caracteres antes do primeiro espaço. Use strcspn() quando quiser encontrar o quão longe está até o primeiro caractere "proibido" (como um delimitador). Veja strcspn() para mais detalhes.

Funções relacionadas

• strcspn() — o complemento; conta os caracteres iniciais não presentes na máscara.
• strpos() — encontra a posição da primeira ocorrência de uma substring.
• substr() — extrai parte de uma string, frequentemente combinado com strspn() para recortar o segmento correspondente.
• strlen() — obtém o comprimento total de uma string.

Conclusão

strspn() responde a uma pergunta precisa: qual é o comprimento da sequência de caracteres permitidos no início desta string? É rápida, sem dependências e bem adequada para tarefas de validação e análise simples. Lembre-se de que é sensível a maiúsculas e minúsculas e baseada em bytes, que para no primeiro caractere fora da máscara, e que sua contraparte strcspn() faz o inverso. Com essas regras em mente, você pode usá-la para escrever verificações de string concisas e eficientes.

Prática