String.prototype.localeCompare()
Baseline
広く利用可能
この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2015年7月以降、すべてのブラウザーで利用可能です。
localeCompare() は String 値のメソッドで、参照文字列がソート順で指定された文字列の前か後か、または同じかを示す数値を返します。Intl.Collator API に対応している実装では、このメソッドは単に Intl.Collator を呼び出します。
大量の文字列を比較する場合、例えば巨大な配列を並べ替えしている時は、Intl.Collator オブジェクトを生成してそれが提供する compare() メソッドを使用したほうがいいでしょう。
試してみましょう
const a = "réservé"; // With accents, lowercase
const b = "RESERVE"; // No accents, uppercase
console.log(a.localeCompare(b));
// 予想される結果: 1
console.log(a.localeCompare(b, "en", { sensitivity: "base" }));
// 予想される結果: 0
構文
localeCompare(compareString)
localeCompare(compareString, locales)
localeCompare(compareString, locales, options)
引数
locales と options 引数は、この関数の動作をカスタマイズし、アプリケーションが書式化の習慣で使用する言語を指定することができます。
Intl.Collator API に対応している実装では、これらの引数はちょうど Intl.Collator() コンストラクターの引数に対応します。Intl.Collator の対応のない実装では、両方の引数を無視し、比較を行うと完全に実装依存の値を返します。一貫性があることだけが必要です。
compareString-
この文字列と比較される文字列です。すべての値は文字列に変換されますので、省略したり
undefinedを渡したりすると、localeCompare()は"undefined"という文字列と比較を行います。これはおそらく望むところではないでしょう。 locales省略可-
BCP 47 言語タグの文字列、またはそのような文字列の配列です。
Intl.Collator()コンストラクターのlocales引数に対応します。Intl.Collatorの対応がない実装では、この引数は無視され、普通はホストのロケールが使用されます。 options省略可-
出力形式を調整するオブジェクトです。
Intl.Collator()コンストラクターのoptions引数に対応します。Intl.Collatorの対応がない実装では、この引数は無視されます。
Intl.Collator() コンストラクター の記事に、locales および options 引数の詳細と使い方が書かれています。
返値
referenceStr が compareString より前に出現するものである場合は負の数です。 referenceStr が compareString より後に出現するものである場合は正の数です。等しい場合は 0 です。
Intl.Collator の実装では、これは new Intl.Collator(locales, options).compare(referenceStr, compareString) と等価です。
解説
referenceStr が compareString より前に来るか、後に来るか、あるいは等しいかを示す整数を返します。
referenceStrがcompareStringより前に出現するものである場合は負の数referenceStrがcompareStringより後に出現するものである場合は正の数- 等しい場合は
0
警告:
返値が正確な -1 または 1 であると思わないでください。
結果の負の整数と正の整数は、ブラウザー間（およびブラウザーのバージョン間）で異なります。これは W3C の仕様が負の値か正の値かとだけ指定しているためです。ブラウザーによっては -2 や 2 を、あるいは他の負の値、正の値を返却するかもしれません。
例
localeCompare() の使用
// 文字 "a" は "c" は負の数になります
"a".localeCompare("c"); // -2 や -1 （あるいはまた別の負の数）
// 単語 "check" はアルファベット順に "against" より後ろなので正の数になります
"check".localeCompare("against"); // 2 や 1 （あるいはまた別の正の数）
// "a" と"a" は等しいので自然数 0 になります
"a".localeCompare("a"); // 0
配列の並べ替え
localeCompare() で、大文字小文字の違いを無視した配列の並べ替えができます。
const 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é']
拡張引数をブラウザーが対応しているか調べる
locales と options の引数は、まだすべてのブラウザーで対応しているわけではありません。
実装がこれらに対応しているか調べるには、引数 "i"（不正な言語タグが除外される要件）を使用して、例外 RangeError を調べてください。
function localeCompareSupportsLocales() {
try {
"foo".localeCompare("bar", "i");
} catch (e) {
return e.name === "RangeError";
}
return false;
}
locales の使用
localeCompare() によって得られる結果は言語間で異なります。アプリケーションのユーザーインターフェイスで使用される言語の整列順を得るには、 locales 引数を使用してその言語（そしてできればいくつかの代替言語）を指定していることを確かめて下さい。
console.log("ä".localeCompare("z", "de")); // 負の数: ドイツ語で ä は a に分類される
console.log("ä".localeCompare("z", "sv")); // 正の数: スウェーデン語では ä は z の後になる
options の使用
localeCompare() によって得られる結果は、options 引数を使用することによってカスタマイズできます。:
// ドイツ語では ä の base letter は a
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0
// スウェーデン語では ä と a は base letter が異なる
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // 正の値
数値の並べ替え
// 既定では "2" > "10"
console.log("2".localeCompare("10")); // 1
// options を使用した数値
console.log("2".localeCompare("10", undefined, { numeric: true })); // -1
// ロケールタグを使用した数値
console.log("2".localeCompare("10", "en-u-kn-true")); // -1
仕様書
| 仕様書 |
|---|
| ECMAScript® 2027 Language Specification # sec-string.prototype.localecompare |
| ECMAScript® 2027 Internationalization API Specification # sup-String.prototype.localeCompare |