String.prototype.localeCompare()

localeCompare() メソッドは、参照文字列がソート順で指定された文字列の前か後か、または同じかを示す数値を返します。Intl.Collator API に対応している実装では、このメソッドは単に Intl.Collator を呼び出します。

大量の文字列を比較する場合、例えば巨大な配列を並べ替えしている時は、Intl.Collator オブジェクトを生成してそれが提供する compare() メソッドを使用したほうがいいでしょう。

試してみましょう

構文

js
localeCompare(compareString)
localeCompare(compareString, locales)
localeCompare(compareString, locales, options)

引数

localesoptions 引数は、この関数の動作をカスタマイズし、アプリケーションが書式化の習慣で使用する言語を指定することができます。

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 引数の詳細と使い方が書かれています。

返値

referenceStrcompareString より前に出現するものである場合はの数です。 referenceStrcompareString より後に出現するものである場合はの数です。等しい場合は 0 です。

Intl.Collator の実装では、これは new Intl.Collator(locales, options).compare(referenceStr, compareString) と等価です。

解説

referenceStrcompareString より前に来るか、後に来るか、あるいは等しいかを示す整数を返します。

  • referenceStrcompareString より前に出現するものである場合は負の数
  • referenceStrcompareString より後に出現するものである場合は正の数
  • 等しい場合は 0

警告: 返値が正確な -1 または 1 であると思わないでください。

結果の負の整数と正の整数は、ブラウザー間(およびブラウザーのバージョン間)で異なります。これは W3C の仕様が負の値か正の値かとだけ指定しているためです。ブラウザーによっては -22 を、あるいは他の負の値、正の値を返却するかもしれません。

localeCompare() の使用

js
// 文字 "a" は "c" は負の数になります
"a".localeCompare("c"); // -2 や -1 (あるいはまた別の負の数)

// 単語 "check" はアルファベット順に "against" より後ろなので正の数になります
"check".localeCompare("against"); // 2 や 1 (あるいはまた別の正の数)

// "a" と"a" は等しいので自然数 0 になります
"a".localeCompare("a"); // 0

配列の並べ替え

localeCompare() で、大文字小文字の違いを無視した配列の並べ替えができます。

js
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é']

拡張引数をブラウザーが対応しているか調べる

localesoptions の引数は、まだすべてのブラウザーで対応しているわけではありません。

実装がこれらに対応しているか調べるには、引数 "i"(不正な言語タグが除外される要件)を使用して、例外 RangeError を調べてください。

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

locales の使用

localeCompare() によって得られる結果は言語間で異なります。アプリケーションのユーザーインターフェイスで使用される言語の整列順を得るには、 locales 引数を使用してその言語(そしてできればいくつかの代替言語)を指定していることを確かめて下さい。

js
console.log("ä".localeCompare("z", "de")); // 負の数: ドイツ語で ä は a に分類される
console.log("ä".localeCompare("z", "sv")); // 正の数: スウェーデン語では ä は z の後になる

options の使用

localeCompare() によって得られる結果は、options 引数を使用することによってカスタマイズできます。:

js
// ドイツ語では ä の base letter は a
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0

// スウェーデン語では ä と a は base letter が異なる
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // 正の値

数値の並べ替え

js
// 既定では "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

仕様書

Specification
ECMAScript Language Specification
# sec-string.prototype.localecompare
ECMAScript Internationalization API Specification
# sup-String.prototype.localeCompare

ブラウザーの互換性

BCD tables only load in the browser

関連情報