str_decrement — Funktion · PHP-Referenz

Signatur

str_decrement(string $string): string

Beschreibung

str_decrement() verringert eine alphanumerische Zeichenkette um eins, analog zu dem, was ++ für das Inkrementieren tut – jedoch als explizite Funktion für das Dekrementieren. Die Funktion funktioniert zeichenweise von rechts nach links und berücksichtigt alphanumerische Zeichen (a–z, A–Z, 0–9).

Der Mechanismus arbeitet wie ein Übertrag: Wird a dekrementiert, ergibt sich z mit einem Übertrag auf die nächste linke Stelle. Ähnlich gilt: A → Z und 0 → 9 mit entsprechendem Übertrag. Die Zeichenkette darf keine Nicht-alphanumerischen Zeichen enthalten, da die Funktion sonst eine ValueError-Exception wirft.

Sinnvoll eingesetzt werden kann str_decrement() beim Arbeiten mit alphanumerischen Identifikatoren, Versionskennzeichnungen, sequenziellen Schlüsseln (z. B. Spaltenbezeichnungen wie in Tabellenkalkulationen) oder überall dort, wo eine rückwärts laufende alphanumerische Sequenz benötigt wird.

Im Gegensatz zum ---Operator, der bei Strings keine Wirkung hat, bietet str_decrement() eine zuverlässige und explizite Möglichkeit, Zeichenketten zu dekrementieren.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Die alphanumerische Zeichenkette, die dekrementiert werden soll. Darf ausschließlich Zeichen aus `a–z`, `A–Z` und `0–9` enthalten. Leerstrings oder Strings mit anderen Zeichen lösen eine `ValueError`-Exception aus.

Rückgabewert

Typ

string

Beschreibung

Gibt die um eins dekrementierte Zeichenkette zurück. Das Ergebnis ist immer gleich lang wie die Eingabe (kein automatisches Kürzen bei Überlauf auf die linke Seite hinaus).

Beispiele

Einfaches Dekrementieren einzelner Zeichen

<?php
echo str_decrement('b');  // a
echo PHP_EOL;
echo str_decrement('B');  // A
echo PHP_EOL;
echo str_decrement('5');  // 4
echo PHP_EOL;
echo str_decrement('Z');  // Y
echo PHP_EOL;

a A 4 Y

Übertrag bei Dekrementierung

<?php
// 'a' wird zu 'z' und erzeugt einen Übertrag auf die nächste Stelle
echo str_decrement('ba');  // az
echo PHP_EOL;
echo str_decrement('a0');  // z9 (Übertrag über Zeichenklassen hinweg)
echo PHP_EOL;
echo str_decrement('AA');  // ZZ
echo PHP_EOL;

az z9 ZZ

Spaltenbezeichnungen einer Tabellenkalkulation rückwärts durchlaufen

<?php
$column = 'D';
$sequence = [];
for ($i = 0; $i < 4; $i++) {
    $sequence[] = $column;
    $column = str_decrement($column);
}
print_r($sequence);
// Gibt D, C, B, A aus

Array ( [0] => D [1] => C [2] => B [3] => A )

ValueError bei ungültigem Eingabe-String

<?php
try {
    str_decrement('a-1'); // Enthält nicht-alphanumerisches Zeichen
} catch (ValueError $e) {
    echo 'Fehler: ' . $e->getMessage() . PHP_EOL;
}

try {
    str_decrement(''); // Leerer String
} catch (ValueError $e) {
    echo 'Fehler: ' . $e->getMessage() . PHP_EOL;
}

Fehler: str_decrement(): Argument #1 ($string) must be composed only of alphanumeric ASCII characters Fehler: str_decrement(): Argument #1 ($string) must be composed only of alphanumeric ASCII characters

// Wichtig · Fallstricke

Wichtig: str_decrement() wirft eine ValueError-Exception, wenn der übergebene String leer ist oder nicht-alphanumerische Zeichen (wie Leerzeichen, Bindestriche, Unterstriche etc.) enthält. Eingaben müssen daher vorab validiert werden.

Zu beachten ist außerdem, dass ein Übertrag über die linke Zeichengrenze hinaus nicht zu einer Verkürzung des Strings führt – der Rückgabewert hat immer die gleiche Länge wie die Eingabe. Das bedeutet: str_decrement('a') ergibt 'z', nicht etwa '' oder einen negativen Wert.

Im Unterschied zum inkrementierenden ++-Operator gibt es für Strings keinen entsprechenden ---Operator in PHP. str_decrement() schließt diese Lücke seit PHP 8.3 explizit.

Siehe auch

str_increment ord chr