strspn — Funktion · PHP-Referenz

Signatur

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

Beschreibung

strspn() durchsucht die Zeichenkette $string ab dem Beginn (oder ab dem optionalen $offset) und zählt, wie viele aufeinanderfolgende Zeichen ausschließlich in der Masken-Zeichenkette $characters vorkommen. Sobald ein Zeichen gefunden wird, das nicht in der Maske enthalten ist, wird gezählt aufgehört.

Die Funktion ist besonders nützlich für einfache Validierungs- oder Parsing-Aufgaben, etwa um zu prüfen, ob eine Eingabe ausschließlich aus erlaubten Zeichen besteht (z. B. nur Ziffern, Buchstaben oder Hexadezimalzeichen), ohne einen regulären Ausdruck einsetzen zu müssen.

Mit den optionalen Parametern $offset und $length lässt sich die Suche auf einen Teilbereich des Strings einschränken. Ein negativer $offset zählt vom Ende des Strings rückwärts, ein negativer $length-Wert schließt die letzten n Zeichen aus dem betrachteten Bereich aus.

Das Gegenstück strcspn() liefert hingegen die Länge des Abschnitts, der ausschließlich aus Zeichen besteht, die nicht in der Maske vorkommen.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Die zu untersuchende Zeichenkette.
$characters Pflicht	string		Die Maske der erlaubten Zeichen. Jedes einzelne Zeichen dieser Zeichenkette gilt als erlaubt.
$offset	int	0	Startposition in `$string`, ab der gesucht wird. Ein negativer Wert zählt vom Ende der Zeichenkette rückwärts.
$length	int	PHP_INT_MAX	Maximale Anzahl zu untersuchender Zeichen ab `$offset`. Ein negativer Wert schließt die letzten `n` Zeichen des Strings aus dem betrachteten Bereich aus.

Rückgabewert

Typ

int

Beschreibung

Gibt die Länge des initialen Abschnitts zurück, der ausschließlich aus Zeichen der Maske besteht. Ist das erste Zeichen bereits nicht in der Maske enthalten, wird 0 zurückgegeben.

Beispiele

Prüfen, ob eine Eingabe nur aus Ziffern besteht

<?php
$input = '12345abc';
$laenge = strspn($input, '0123456789');

if ($laenge === strlen($input)) {
    echo 'Die Eingabe besteht ausschließlich aus Ziffern.';
} else {
    echo "Nur die ersten {$laenge} Zeichen sind Ziffern: " . substr($input, 0, $laenge);
}
// Ausgabe: Nur die ersten 5 Zeichen sind Ziffern: 12345

Nur die ersten 5 Zeichen sind Ziffern: 12345

Hexadezimal-Präfix einer Zeichenkette ermitteln

<?php
$hex = '1a2f3gxyz';
$hexZeichen = '0123456789abcdefABCDEF';
$laenge = strspn($hex, $hexZeichen);

echo 'Gültiger Hex-Anteil: ' . substr($hex, 0, $laenge) . PHP_EOL;
echo 'Länge: ' . $laenge . PHP_EOL;
// Nur '1a2f3' ist gültiges Hex; 'g' bricht die Sequenz ab

Gültiger Hex-Anteil: 1a2f3 Länge: 5

Verwendung von Offset und Length

<?php
$string = 'aaa111bbb222';
// Untersuche ab Position 3, maximal 6 Zeichen
$laenge = strspn($string, '123', 3, 6);
echo $laenge; // 3 — '111' sind Ziffern, dann kommt 'b'

3

// Wichtig · Fallstricke

Achtung: strspn() arbeitet byte-weise und ist nicht multibyte-fähig. Bei UTF-8-Strings mit Zeichen außerhalb des ASCII-Bereichs können unerwartete Ergebnisse entstehen. Für Multibyte-Zeichenketten gibt es keine direkte MB-Entsprechung; hier sind reguläre Ausdrücke mit preg_match() und dem u-Modifier empfehlenswert.

Die Maske $characters wird als Zeichenmenge behandelt, nicht als regulärer Ausdruck oder Bereichsangabe. Das Zeichen - beispielsweise steht also nur für einen Bindestrich, nicht für einen Zeichenbereich.

Siehe auch

strcspn str_contains preg_match substr ctype_digit