Signatur
Beschreibung
variant_cmp() vergleicht zwei Werte vom Typ VARIANT (COM-Datentyp unter Windows) miteinander. Die Funktion ist Teil der COM-Erweiterung von PHP und ermöglicht den typsicheren Vergleich von VARIANT-Objekten, wie sie bei der Arbeit mit COM-Objekten und ActiveX-Komponenten unter Windows auftreten.
Der Rückgabewert ist ähnlich wie bei strcmp(): ein negativer Wert, wenn $left kleiner als $right ist, 0 bei Gleichheit, und ein positiver Wert, wenn $left größer ist. Der Vergleich berücksichtigt dabei das angegebene Gebietsschema ($lcid), was besonders bei Zeichenfolgenvergleichen relevant ist.
Über den Parameter $flags lässt sich das Vergleichsverhalten weiter steuern, etwa ob Groß-/Kleinschreibung ignoriert werden soll. Typische Flag-Werte sind Konstanten wie NORM_IGNORECASE, NORM_IGNORENONSPACE oder andere NORM_*-Konstanten aus der Windows-API.
Diese Funktion ist ausschließlich unter Windows verfügbar und setzt die PHP-COM-Erweiterung (php_com_dotnet.dll) voraus. Sie ist primär nützlich, wenn man Ergebnisse von COM-Aufrufen direkt vergleichen möchte, ohne die VARIANT-Werte vorher in native PHP-Typen umwandeln zu müssen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $left Pflicht | mixed | Der linke Operand des Vergleichs. Kann ein VARIANT-Objekt oder ein skalarer PHP-Wert sein, der automatisch in einen VARIANT umgewandelt wird. |
|
| $right Pflicht | mixed | Der rechte Operand des Vergleichs. Kann ein VARIANT-Objekt oder ein skalarer PHP-Wert sein, der automatisch in einen VARIANT umgewandelt wird. |
|
| $lcid | int | LOCALE_SYSTEM_DEFAULT | Der Locale-Identifier (LCID), der für den Vergleich verwendet wird. Standardmäßig wird das Systemgebietsschema verwendet (LOCALE_SYSTEM_DEFAULT). Relevant vor allem bei Zeichenfolgenvergleichen. |
| $flags | int | 0 | Optionale Flags zur Steuerung des Vergleichs, z. B. NORM_IGNORECASE zum Ignorieren der Groß-/Kleinschreibung. Mehrere Flags können per bitweisem ODER (|) kombiniert werden. |
Rückgabewert
$left kleiner als $right ist, 0 bei Gleichheit und einen positiven Wert, wenn $left größer ist. Die genauen Rückgabewerte entsprechen den Windows-VARCMP-Konstanten: VARCMP_LT (-1), VARCMP_EQ (0), VARCMP_GT (1) oder VARCMP_NULL (2) wenn einer der Werte NULL ist.Beispiele
Grundlegender Vergleich zweier VARIANT-Werte
<?php
// Nur unter Windows mit aktivierter COM-Erweiterung verfügbar
$a = new VARIANT(42, VT_I4);
$b = new VARIANT(100, VT_I4);
$result = variant_cmp($a, $b);
if ($result < 0) {
echo "a ist kleiner als b";
} elseif ($result === 0) {
echo "a ist gleich b";
} else {
echo "a ist größer als b";
}
Zeichenfolgenvergleich mit Ignorieren der Groß-/Kleinschreibung
<?php
// Nur unter Windows mit aktivierter COM-Erweiterung verfügbar
$str1 = new VARIANT("Hallo", VT_BSTR);
$str2 = new VARIANT("hallo", VT_BSTR);
// Vergleich mit NORM_IGNORECASE-Flag
$result = variant_cmp($str1, $str2, LOCALE_SYSTEM_DEFAULT, NORM_IGNORECASE);
if ($result === 0) {
echo "Die Strings sind (ohne Berücksichtigung der Groß-/Kleinschreibung) gleich.";
} else {
echo "Die Strings sind unterschiedlich.";
}
// Wichtig · Fallstricke
Plattformabhängigkeit: variant_cmp() ist ausschließlich unter Windows verfügbar und erfordert die aktivierte COM-Erweiterung (extension=php_com_dotnet.dll in der php.ini). Auf Linux- oder macOS-Systemen steht diese Funktion nicht zur Verfügung.
NULL-Handling: Wenn einer der übergebenen Werte NULL ist, gibt die Funktion den Wert VARCMP_NULL (2) zurück, was bei normalen Vergleichen (< 0, === 0, > 0) zu unerwarteten Ergebnissen führen kann. Prüfe daher vor dem Vergleich, ob die Werte nicht NULL sind.
Typ-Koercion: Skalare PHP-Werte werden automatisch in VARIANT-Objekte umgewandelt. Dabei kann es zu impliziten Typumwandlungen kommen, die den Vergleich beeinflussen.