Ds\Sequence — Interface · PHP-Referenz

Signatur

interface Ds\Sequence extends Ds\Collection

Beschreibung

Ds\Sequence ist ein Interface aus der Data Structures-Erweiterung (ext-ds) und erweitert Ds\Collection. Es beschreibt eine geordnete Folge von Elementen, bei der die Reihenfolge stets erhalten bleibt und jedes Element über einen nullbasierten, ganzzahligen Index erreichbar ist.

Das Interface wird von den konkreten Klassen Ds\Vector und Ds\Deque implementiert. Es legt alle typischen Sequenzoperationen fest: Einfügen, Entfernen, Sortieren, Filtern, Suchen sowie Index-basierter Zugriff. Damit bietet es eine typsichere, leistungsfähigere und speichereffizientere Alternative zu PHP-Arrays, wenn eine streng geordnete Liste benötigt wird.

Als Interface eignet sich Ds\Sequence hervorragend für Type-Hints in Funktionen oder Methoden, die wahlweise einen Ds\Vector oder eine Ds\Deque akzeptieren sollen – ohne die konkrete Implementierung zu binden. Dies fördert flexible, austauschbare Datenstrukturen im Anwendungscode.

Ds\Vector: Optimiert für wahlfreien Index-Zugriff und Iterationen.
Ds\Deque: Optimiert für effizientes Einfügen und Entfernen an beiden Enden.

Beispiele

Type-Hint mit Ds\Sequence für Vector und Deque

<?php
require 'vendor/autoload.php'; // oder pecl-Extension laden

function sumSequence(Ds\Sequence $seq): float|int {
    $sum = 0;
    foreach ($seq as $value) {
        $sum += $value;
    }
    return $sum;
}

$vector = new Ds\Vector([1, 2, 3, 4, 5]);
$deque  = new Ds\Deque([10, 20, 30]);

echo sumSequence($vector) . PHP_EOL; // 15
echo sumSequence($deque)  . PHP_EOL; // 60

15 60

Gemeinsame Sequenz-Methoden über das Interface nutzen

<?php
require 'vendor/autoload.php';

function demonstrateSequence(Ds\Sequence $seq): void {
    $seq->push('a', 'b', 'c');
    echo 'Anzahl: ' . $seq->count() . PHP_EOL;
    echo 'Erstes Element: ' . $seq->first() . PHP_EOL;
    echo 'Letztes Element: ' . $seq->last()  . PHP_EOL;

    $seq->sort();
    echo 'Sortiert: ';
    foreach ($seq as $item) {
        echo $item . ' ';
    }
    echo PHP_EOL;

    $filtered = $seq->filter(fn($v) => $v !== 'b');
    echo 'Gefiltert: ';
    foreach ($filtered as $item) {
        echo $item . ' ';
    }
    echo PHP_EOL;
}

demonstrate Sequence(new Ds\Vector());
demonstrate Sequence(new Ds\Deque());

Anzahl: 3 Erstes Element: a Letztes Element: c Sortiert: a b c Gefiltert: a c Anzahl: 3 Erstes Element: a Letztes Element: c Sortiert: a b c Gefiltert: a c

// Wichtig · Fallstricke

Voraussetzung: Die ext-ds-Erweiterung muss installiert sein (pecl install ds oder über Composer mit php-ds/php-ds als Polyfill). Sie ist nicht standardmäßig im PHP-Kern enthalten.

Indexgrenzen: Zugriffe auf ungültige Indizes lösen eine OutOfRangeException aus. Negative Indizes (z. B. -1 für das letzte Element) werden von den implementierenden Klassen unterstützt, jedoch nicht direkt vom Interface definiert – das Verhalten ist implementierungsabhängig.

Kein direktes Instanziieren: Da Ds\Sequence ein Interface ist, kann es nicht direkt instanziiert werden. Immer eine konkrete Klasse wie Ds\Vector oder Ds\Deque verwenden.

Siehe auch

Ds\Vector Ds\Deque Ds\Collection Ds\Map Ds\Set