String.prototype.localeCompare()

Les arguments locales et options permettent de définir la locale et des options pour adapter le comportement de la fonction. Pour les anciennes implémentations qui ignorent les arguments locales et options, l'ordre de tri utilisé sera entièrement dépendant de l'implémentation.

chaineAComparer

La chaîne avec laquelle on souhaite comparer la chaîne de caractères courante.

locales et options

Ces arguments permettent d'adapter le comportement de la fonction pour que les applications puissent indiquer la locale dont les conventions doivent être utilisées. Pour les implémentations qui ignorent les arguments locales et options, la locale et le format de la chaîne qui est renvoyée dépendent entièrement de l'implémentation.

Voir la page du constructeur Intl.Collator() pour plus de détails sur ces paramètres et leur utilisation.

Un nombre négatif si la chaîne de caractères appelante est ordonnée avant la chaîne passée en argument, un nombre positif si elle se situe après, 0 si les deux chaînes sont équivalentes.

Cette méthode renvoie un nombre entier qui indique si la chaîne de caractères courante se situe avant ou après la chaîne passée en argument selon l'ordre lexicographique tenant compte de la locale.

Cette méthode renvoie :

• un nombre négatif si la chaîne de caractères courant se situe avant la chaîne chaineAComparer
• un nombre positif si elle se situe après
• 0 si les deux chaînes sont équivalentes selon cet ordre.

Pour comparer un grand nombre de chaînes de caractères, par exemple pour trier de grands tableaux, il est préférable de créer un objet Intl.Collator et d'utiliser la fonction fournie par la propriété compare.

L'exemple qui suit illustre les différents cas de figures lors de la comparaison des chaînes de caractères :

// La lettre "a" est située avant la lettre "c"
// On a donc une valeur négative
'a'.localeCompare('c'); // -2, ou -1, ou toute autre valeur négative

// Alphabétiquement, le mot "coucou" est situé après
// "avion", la valeur est donc positive
'coucou'.localeCompare('avion')); // 2, ou 1, ou toute autre valeur positive

// Deux chaînes de caractères identiques sont équivalentes : 0
'a'.localeCompare('a'); // 0

localeCompare() permet de trier un tableau sans tenir compte de la casse :

var items = ["réservé", "Premier", "Cliché", "communiqué", "café", "Adieu"];
items.sort((a, b) => a.localeCompare(b, "fr", { ignorePunctuation: true }));
// ['Adieu', 'café', 'Cliché', 'communiqué', 'Premier', 'réservé']

Les arguments locales et options ne sont pas pris en charge par tous les navigateurs.

Pour vérifier qu'une implémentation implémente ces paramètres, il est possible d'utiliser un cas d'erreur quand on utilise une balise de langue incorrecte (ce qui provoque une exception RangeError) :

function localeCompareSupportsLocales() {
  try {
    "toto".localeCompare("truc", "i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}

Les résultats fournis par la méthode localeCompare() peuvent varier selon les locales utilisées. Pour spécifier la locale à utiliser pour votre application, utilisez l'argument locales (éventuellement en incluant des locales de recours) :

console.log("ä".localeCompare("z", "de")); // une valeur négative : en allemand ä est avant z
console.log("ä".localeCompare("z", "sv")); // une valeur positive : en suédois, ä arrive après z

Les résultats construits par la méthode localeCompare() peuvent être adaptés grâce au paramètre options :

// en allemand, ä et a ont la même lettre de base
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0

// en suédois, ä et a n'ont pas la même lettre de base
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // une valeur positive

• Intl.Collator