variant_and — Funktion · PHP-Referenz

Signatur

variant_and(mixed $left, mixed $right): mixed

Beschreibung

variant_and() ist Teil der COM/Variant-Erweiterung von PHP und führt eine bitweise UND-Operation auf zwei Variant-Werte durch. Variants sind ein Datentyp, der in der Windows COM-Automatisierung verwendet wird und beliebige Typen aufnehmen kann.

Die Funktion entspricht dem &-Operator, arbeitet jedoch typsicher auf Variant-Objekten, wie sie beim Umgang mit COM-Objekten unter Windows entstehen. PHP konvertiert die Operanden intern in den passenden Typ, bevor die Operation durchgeführt wird.

Diese Funktion ist hauptsächlich dann relevant, wenn man über PHP mit Windows-COM-Schnittstellen (z. B. Microsoft Office, ActiveX-Komponenten) arbeitet und bitweise Operationen auf zurückgegebenen Variant-Werten durchführen muss. Für rein PHP-interne Berechnungen ohne COM-Kontext ist der native &-Operator vorzuziehen.

Die Funktion ist ausschließlich unter Windows verfügbar, da sie von der COM-Erweiterung abhängt, die nur auf dieser Plattform unterstützt wird.

Parameter

Name	Typ	Default	Beschreibung
$left Pflicht	mixed		Der linke Operand der bitweisen UND-Operation. Kann ein `VARIANT`-Objekt oder ein PHP-Skalarwert sein, der intern in ein Variant konvertiert wird.
$right Pflicht	mixed		Der rechte Operand der bitweisen UND-Operation. Kann ein `VARIANT`-Objekt oder ein PHP-Skalarwert sein, der intern in ein Variant konvertiert wird.

Rückgabewert

Typ

mixed

Beschreibung

Gibt das Ergebnis der bitweisen UND-Operation als Variant zurück. Der genaue Rückgabetyp hängt von den Typen der übergebenen Operanden ab. Bei einem Fehler (z. B. inkompatible Typen) wird eine com_exception geworfen.

Beispiele

Bitweises UND auf zwei Integer-Variant-Werte

<?php
// Einfaches Beispiel mit zwei Integer-Werten als Variant
$a = new VARIANT(12, VT_I4); // 12 = 1100 in Binär
$b = new VARIANT(10, VT_I4); // 10 = 1010 in Binär

$result = variant_and($a, $b);
// 1100 & 1010 = 1000 = 8
echo (int) $result; // Ausgabe: 8

8

Bitweises UND mit PHP-Skalaren (automatische Konvertierung)

<?php
// PHP-Skalare werden automatisch in Variants umgewandelt
$flags = new VARIANT(0b1111, VT_I4); // Alle Bits gesetzt: 15
$mask  = 0b1010;                      // Maske: 10

$result = variant_and($flags, $mask);
echo (int) $result; // 1111 & 1010 = 1010 = 10

10

Verwendung im COM-Kontext mit Fehlerbehandlung

<?php
try {
    $a = new VARIANT(255, VT_I4);
    $b = new VARIANT(170, VT_I4); // 10101010

    $result = variant_and($a, $b);
    // 11111111 & 10101010 = 10101010 = 170
    echo 'Ergebnis: ' . (int) $result;
} catch (com_exception $e) {
    echo 'COM-Fehler: ' . $e->getMessage();
}

Ergebnis: 170

// Wichtig · Fallstricke

Plattformabhängigkeit: variant_and() ist ausschließlich unter Windows verfügbar und erfordert die aktivierte PHP COM-Erweiterung (extension=com_dotnet in der php.ini). Auf Linux/macOS-Systemen ist diese Funktion nicht verfügbar.

Typkonvertierung: Bei inkompatiblen Typen (z. B. Strings, die nicht in eine Ganzzahl konvertierbar sind) kann eine com_exception ausgelöst werden. Es empfiehlt sich daher, immer numerisch typisierte Variants (VT_I2, VT_I4 etc.) zu verwenden.

Kein Ersatz für den nativen Operator: Für PHP-interne Berechnungen ohne COM-Bezug sollte stets der native &-Operator verwendet werden, da er deutlich performanter und portabler ist.

Siehe auch

variant_or variant_xor variant_not variant_eqv variant_imp