collator_compare — Funktion · PHP-Referenz

Signatur

collator_compare(Collator $object, string $string1, string $string2): int|false

Beschreibung

collator_compare() ist die prozedurale Variante der Methode Collator::compare() und ermöglicht den lokalisierungsgerechten Vergleich zweier Unicode-Strings. Im Gegensatz zu einfachen Byte-Vergleichen (strcmp()) berücksichtigt diese Funktion sprachspezifische Sortierregeln – etwa Umlaute im Deutschen, Akzente im Französischen oder locale-abhängige Groß-/Kleinschreibungsregeln.

Die Funktion wird üblicherweise beim Sortieren von Strings in internationalisierten Anwendungen eingesetzt. Das Collator-Objekt, das z. B. mit collator_create() erzeugt wird, legt dabei die Locale und weitere Vergleichsoptionen (z. B. Stärke, Normalisierung) fest.

Das Rückgabeverhalten entspricht dem von strcmp(): ein negativer Wert bedeutet, dass $string1 kleiner als $string2 ist, 0 bedeutet Gleichheit, und ein positiver Wert bedeutet, dass $string1 größer ist. Dieser Rückgabewert lässt sich direkt als Vergleichsfunktion für usort() oder ähnliche Sortierfunktionen verwenden.

Die Funktion erfordert die Intl-Erweiterung (intl), die ab PHP 5.3.0 gebündelt ist und in den meisten Umgebungen standardmäßig aktiviert ist.

Parameter

Name	Typ	Beschreibung
$object Pflicht	Collator	Ein `Collator`-Objekt, das mit `collator_create()` oder `new Collator()` erzeugt wurde und die Locale sowie Vergleichsoptionen enthält.
$string1 Pflicht	string	Der erste zu vergleichende Unicode-String.
$string2 Pflicht	string	Der zweite zu vergleichende Unicode-String.

Rückgabewert

Typ

int|false

Beschreibung

Gibt einen negativen Ganzzahlwert zurück, wenn $string1 kleiner als $string2 ist, 0 bei Gleichheit und einen positiven Wert, wenn $string1 größer als $string2 ist. Im Fehlerfall wird false zurückgegeben.

Beispiele

Einfacher Vergleich zweier deutscher Strings

<?php
$collator = collator_create('de_DE');

$result = collator_compare($collator, 'Äpfel', 'Banane');

if ($result < 0) {
    echo '"Äpfel" kommt vor "Banane"';
} elseif ($result > 0) {
    echo '"Äpfel" kommt nach "Banane"';
} else {
    echo '"Äpfel" und "Banane" sind gleichwertig';
}

"Äpfel" kommt vor "Banane"

Lokalisiertes Sortieren eines Arrays mit usort()

<?php
$collator = collator_create('de_DE');

$woerter = ['Zebra', 'Äpfel', 'orange', 'Banane', 'über'];

usort($woerter, function (string $a, string $b) use ($collator): int {
    return collator_compare($collator, $a, $b);
});

print_r($woerter);

Array ( [0] => Äpfel [1] => Banane [2] => orange [3] => über [4] => Zebra )

Vergleich mit unterschiedlicher Locale (Schwedisch)

<?php
// Im Schwedischen wird 'V' und 'W' oft gleich behandelt
$collatorSv = collator_create('sv_SE');
$collatorDe = collator_create('de_DE');

$string1 = 'Vasa';
$string2 = 'Wasa';

echo 'Schwedisch: ' . collator_compare($collatorSv, $string1, $string2) . PHP_EOL;
echo 'Deutsch:    ' . collator_compare($collatorDe, $string1, $string2) . PHP_EOL;

Schwedisch: 0 Deutsch: -1

// Wichtig · Fallstricke

Fehlerbehandlung: Bei ungültigem Collator-Objekt oder internem ICU-Fehler gibt die Funktion false zurück. Der aufgetretene Fehler lässt sich über collator_get_error_code() und collator_get_error_message() abfragen.

Stärke des Vergleichs: Über collator_set_strength() lässt sich steuern, ob Groß-/Kleinschreibung, Akzente oder andere Unterschiede beim Vergleich berücksichtigt werden. Mit Collator::PRIMARY werden z. B. nur Basiszeichen verglichen, Akzente und Groß-/Kleinschreibung werden ignoriert.

Intl-Erweiterung erforderlich: Diese Funktion steht nur zur Verfügung, wenn die intl-Erweiterung aktiviert ist. Die Verfügbarkeit lässt sich mit extension_loaded('intl') prüfen.

Siehe auch

collator_create collator_sort collator_set_strength collator_get_error_code collator_get_error_message strcmp usort