Ds\Pair — Klasse · PHP-Referenz

Signatur

class Ds\Pair implements JsonSerializable

Beschreibung

Ds\Pair ist eine einfache Datenstruktur aus der Data Structures-Erweiterung (ext-ds), die ein einzelnes Schlüssel-Wert-Paar kapselt. Sie wird vor allem beim Iterieren über eine Ds\Map zurückgegeben: Jedes Element der Map ist ein Ds\Pair-Objekt mit den öffentlichen Eigenschaften $key und $value.

Im Gegensatz zu einem einfachen assoziativen Array erlaubt Ds\Pair beliebige Typen als Schlüssel – auch Objekte, Arrays oder andere Nichtskalare. Das macht es insbesondere in Kombination mit Ds\Map nützlich, wenn Objekte als Map-Schlüssel benötigt werden.

Ds\Pair-Objekte können direkt mit new Ds\Pair($key, $value) erzeugt werden. Die Eigenschaften key und value sind öffentlich zugänglich und können nach der Erzeugung auch verändert werden, da es sich formal um öffentliche Felder handelt.

Über die Implementierung von JsonSerializable lässt sich ein Ds\Pair einfach mit json_encode() serialisieren; das Ergebnis ist ein JSON-Objekt mit den Schlüsseln "key" und "value".

Parameter

Name	Typ	Default	Beschreibung
$key	mixed	null	Der Schlüssel des Paares. Kann ein beliebiger PHP-Wert sein, also auch ein Objekt oder Array.
$value	mixed	null	Der Wert des Paares. Kann ein beliebiger PHP-Wert sein.

Rückgabewert

Typ

Beispiele

Direktes Erstellen und Verwenden eines Ds\Pair

<?php
require_once 'vendor/autoload.php'; // oder ext-ds laden

$pair = new Ds\Pair('name', 'Alice');

echo $pair->key;   // name
echo PHP_EOL;
echo $pair->value; // Alice
echo PHP_EOL;

// Eigenschaften können geändert werden
$pair->value = 'Bob';
echo $pair->value; // Bob
echo PHP_EOL;

// JSON-Serialisierung
echo json_encode($pair); // {"key":"name","value":"Bob"}

name Alice Bob {"key":"name","value":"Bob"}

Ds\Pair beim Iterieren über eine Ds\Map

<?php
$map = new Ds\Map();

$keyObj = new stdClass();
$keyObj->id = 42;

$map->put($keyObj, 'Objekt-Wert');
$map->put('stringKey', 'String-Wert');

foreach ($map as $pair) {
    // $pair ist eine Instanz von Ds\Pair
    var_dump(get_class($pair)); // string(7) "Ds\Pair"
    var_dump($pair->key);
    var_dump($pair->value);
    echo '---' . PHP_EOL;
}

string(7) "Ds\Pair" object(stdClass)#1 (1) { ["id"]=> int(42) } string(11) "Objekt-Wert" --- string(9) "stringKey" string(11) "String-Wert" ---

copy()-Methode: Flache Kopie erzeugen

<?php
$original = new Ds\Pair('foo', [1, 2, 3]);
$copy = $original->copy();

$copy->key = 'bar';

echo $original->key; // foo — Original unverändert
echo PHP_EOL;
echo $copy->key;     // bar
echo PHP_EOL;

// Achtung: flache Kopie — Array-Referenz bleibt!
$copy->value[] = 4;
print_r($original->value); // enthält NICHT 4, da Array-Zuweisung copy-on-write

foo bar Array ( [0] => 1 [1] => 2 [2] => 3 )

// Wichtig · Fallstricke

Erweiterung erforderlich: Ds\Pair gehört zur php-ds-Erweiterung (ext-ds). Diese muss entweder über PECL (pecl install ds) installiert oder via Composer (composer require php-ds/php-ds) als Polyfill eingebunden sein.

Flache Kopie: Die Methode copy() erzeugt nur eine flache Kopie. Bei Objekten als key oder value wird lediglich die Referenz kopiert, nicht das Objekt selbst. Änderungen an dem referenzierten Objekt wirken sich auf Original und Kopie aus.

Nicht zur direkten Map-Manipulation: Ein nachträgliches Ändern der Eigenschaften eines aus einer Ds\Map erhaltenen Ds\Pair-Objekts hat keinen Einfluss auf den Map-Inhalt, da die Iteration eine Kopie des Paares liefert.

Siehe auch

Ds\Map Ds\Sequence JsonSerializable Ds\Collection