strcspn()

Einführung

Die Funktion strcspn() in PHP gibt die Länge des Anfangssegments eines Strings zurück, das keines der Zeichen aus einem zweiten String enthält. Mit anderen Worten: Sie zählt, wie viele Zeichen am Anfang eines Strings gelesen werden können, bevor ein „Stopp"-Zeichen auftritt. Diese Seite erläutert die Syntax, die optionalen Parameter $start und $length, das Verhalten der Funktion in Sonderfällen und den Unterschied zur verwandten Funktion strspn().

Der Name lässt sich als „String-Komplement-Spanne" lesen: Sie erfasst den Teil des Strings, der nicht mit dem angegebenen Zeichensatz übereinstimmt. Typische Anwendungsfälle sind das Messen, wie weit ein Token vor einem Trennzeichen reicht, das Prüfen, ob ein Präfix frei von verbotenen Zeichen ist, und das einfache Parsen ohne regulären Ausdruck.

Syntax

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

Die Funktion gibt ein int zurück: die Anzahl der führenden Zeichen (innerhalb des Scanfensters), die in $characters nicht vorhanden sind. Befindet sich das allererste Zeichen in der Menge, wird 0 zurückgegeben.

Hinweis: strcspn() arbeitet auf Bytes, nicht auf Multibyte-Zeichen. Für UTF-8-Strings mit Nicht-ASCII-Zeichen ist stattdessen ein regulärer Ausdruck (preg_match) zu bevorzugen.

Grundlegendes Beispiel

Hier wird "Hello World" nach dem ersten Vorkommen von o oder e durchsucht. Vom Anfang an ist H sicher, aber das nächste Zeichen e befindet sich in der Menge, sodass das sichere Anfangssegment nur "H" ist und die Funktion 1 zurückgibt.

Wenn kein Stopp-Zeichen vorhanden ist

Wenn keines der Zeichen aus $characters im gescannten Bereich vorkommt, gibt die Funktion die vollständige Länge dieses Bereichs zurück:

<?php

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

Dies ist nützlich, um zu prüfen, ob ein Präfix vollständig frei von einer Zeichenmenge ist – gibt der Rückgabewert die Stringlänge an, ist der String sauber.

Ein praktisches Beispiel: Token bis zu einem Trennzeichen lesen

Eine häufige Anwendung in der Praxis ist das Messen, wie viele Zeichen vor einem Trennzeichen stehen. Die von strcspn() zurückgegebene Zahl ist genau die Länge, die an substr() übergeben werden kann, um den führenden Token zu extrahieren:

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

Die erste Ziffer (1) befindet sich an Index 7, sodass das nicht-numerische Präfix "price: " 7 Zeichen lang ist. Dieses Präfix wird dann mit substr() ausgeschnitten.

Verwendung von $start und $length

Die optionalen Parameter $offset und $length begrenzen den Scan auf ein Fenster des Strings:

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

Beim ersten Aufruf beginnt der Scan bei Offset 6, wo der Teilstring "World" beginnt; dessen erstes Zeichen W befindet sich in der Stopp-Menge, daher ist das Ergebnis 0. Beim zweiten Aufruf ist das Fenster auf "Hello" begrenzt, und das erste l steht an Index 2, sodass das Ergebnis 2 ist.

strcspn() vs. strspn()

Diese beiden Funktionen sind Spiegelbilder voneinander:

• strspn() zählt die führenden Zeichen, die in der Zeichenmenge enthalten sind (die Spanne stimmt überein).
• strcspn() zählt die führenden Zeichen, die nicht in der Menge sind (die Komplement-Spanne).

Verwenden Sie strspn(), wenn Sie eine Erlaubnisliste haben („Wie lang ist die Folge gültiger Zeichen?"), und strcspn(), wenn Sie eine Stoppliste haben („Wie weit geht es, bis ein verbotenes Zeichen auftritt?").

Verwandte Funktionen

• strpos() — findet die Position eines einzelnen Teilstrings statt eines beliebigen Zeichens aus einer Menge.
• strstr() — gibt den Teil eines Strings ab der ersten Übereinstimmung zurück.
• strlen() — gibt die Gesamtlänge eines Strings zurück.
• strtok() — teilt einen String anhand einer Menge von Trennzeichen in Token auf.

Fazit

strcspn() ist ein schneller, regex-freier Weg, um zu messen, wie viele Zeichen am Anfang eines Strings frei von einer bestimmten Menge sind. Da sie eine Länge zurückgibt, lässt sie sich gut mit substr() kombinieren, um führende Token zu extrahieren, und ergänzt strspn() für das Scannen mit Erlaubnislisten. Beachten Sie, dass sie auf Bytes arbeitet – verwenden Sie daher preg_match(), wenn eine multibyte-fähige Übereinstimmung erforderlich ist.

Übung