variant_mod — Funktion · PHP-Referenz

Signatur

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

Beschreibung

variant_mod() führt eine Modulo-Operation auf zwei COM-Variant-Werten durch und gibt den Rest der ganzzahligen Division von $left durch $right zurück. Die Funktion gehört zur PHP-COM-Erweiterung und ist speziell für die Arbeit mit Windows-COM-Objekten und deren Variant-Datentypen konzipiert.

Beide Operanden werden vor der Berechnung in ganzzahlige Werte konvertiert. Das Ergebnis entspricht damit dem mathematischen Ausdruck $left % $right, jedoch unter Berücksichtigung der COM-Variant-Typregeln. Der Einsatz ist sinnvoll, wenn mit nativen COM-Objekten gearbeitet wird, bei denen PHP-Operatoren nicht zuverlässig den korrekten Variant-Typ liefern.

Die Funktion ist ausschließlich unter Windows verfügbar und setzt die aktivierte com_dotnet-Erweiterung voraus. Für reine PHP-Berechnungen ohne COM-Kontext sollte stattdessen der normale Modulo-Operator % verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$left Pflicht	mixed		Der Dividend – ein Variant-Wert oder ein kompatibler PHP-Wert, der als Variant interpretiert werden kann.
$right Pflicht	mixed		Der Divisor – ein Variant-Wert oder ein kompatibler PHP-Wert. Darf nicht null oder 0 sein, da sonst eine Division durch null ausgelöst wird.

Rückgabewert

Typ

mixed

Beschreibung

Gibt ein Variant-Objekt zurück, das den ganzzahligen Rest der Division enthält. Im Fehlerfall (z. B. Division durch null) wird eine com_exception ausgelöst.

Beispiele

Einfache Modulo-Berechnung mit Variant-Werten

<?php
// Setzt eine Windows-Umgebung mit aktivierter COM-Erweiterung voraus
$left  = new VARIANT(17, VT_I4);
$right = new VARIANT(5,  VT_I4);

$result = variant_mod($left, $right);

echo "17 mod 5 = " . (int)$result; // Ergibt 2

17 mod 5 = 2

Modulo mit normalen PHP-Werten (automatische Konvertierung)

<?php
// PHP-Zahlen werden automatisch in Variants konvertiert
$result = variant_mod(29, 6);

echo "29 mod 6 = " . (int)$result; // Ergibt 5

29 mod 6 = 5

// Wichtig · Fallstricke

Nur Windows: variant_mod() steht ausschließlich auf Windows-Systemen mit aktivierter com_dotnet-Erweiterung zur Verfügung. Auf anderen Plattformen führt der Aufruf zu einem fatalen Fehler.

Division durch null: Wird $right als 0 übergeben, wirft die Funktion eine com_exception. Der Aufruf sollte daher in einem try/catch-Block gesichert werden.

Ganzzahl-Konvertierung: Fließkomma-Werte werden vor der Berechnung zu Ganzzahlen gekürzt (nicht gerundet), was bei der Verwendung von Float-Varianten zu unerwarteten Ergebnissen führen kann.

Siehe auch

variant_div variant_mul variant_sub variant_add variant_idiv