String.prototype.localeCompare()

localeCompare() メソッドは参照文字列がソート順で引数で与えられた文字列と大なり、小なり、等しいとなるかどうかを示す数値を返します。

新しいlocalesoptions 引数によってアプリケーションはソート順で使われる言語を指定し関数の振る舞いをカスタマイズできます。古い実装では、locales引数とoptions引数は無視されます。使用されるローケルとソート順は完全に実装依存しています。

構文

referenceStr.localeCompare(compareString[, locales[, options]])

引数

compareString

referenceStr と比較される文字列。

locales 、 options

これらの引数は関数の振る舞いをカスタマイズし、使用されるべきフォーマット規約の言語をアプリケーションに決めさせます。引数 locales 、 options を無視する実装においては、使用されるロケールと返却される文字列の書式は完全に実装依存となります。

これらのパラメーターの詳細及び使用方法については Intl.Collator() コンストラクター を見てください。

戻り値

referenceStr が compareString より前に出現する場合は負数、 referenceStr が compareString より後に出現する場合は正数、等しい場合は 0 。

説明

referenceStr が compareString より辞書順で先に来るか、後に来るか、あるいは等しいかを示す整数を返します。

  • referenceStr が compareString より先に出現する場合は負数
  • referenceStr が compareString より後に出現する場合は正数
  • 等しい場合は 0

戻り値が厳密に -1 や 1 であると考えないように

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

パフォーマンス

巨大な配列のソートなど大量の文字列を比較する場合は Intl.Collator オブジェクトを作成し、 compare プロパティで提供される関数を利用すると良いでしょう。

localeCompare()を使う

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

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

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

配列のソート

localeCompare() は case-insensitive な配列のソートを行います。

let 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 {
    'a'.localeCompare​('b', '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 letters
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // a positive value

数字のソート

// デフォルトでは "2" > "10"
console.log("2".localeCompare("10")); // 1

// オプションを使った数字
console.log("2".localeCompare("10", undefined, {numeric: true})); // -1

// ロケールタグを使った数字
console.log("2".localeCompare("10", "en-u-kn-true")); // -1

仕様

Specification
ECMAScript (ECMA-262)
String.prototype.localeCompare の定義
ECMAScript Internationalization API (ECMA-402)
String.prototype.localeCompare の定義

ブラウザ実装状況

Update compatibility data on GitHub
デスクトップモバイルサーバー
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung InternetNode.js
localeCompareChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 1IE 完全対応 5.5Opera 完全対応 7Safari 完全対応 3WebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 10.1Safari iOS 完全対応 1Samsung Internet Android 完全対応 1.0nodejs 完全対応 0.1.100
localesChrome 完全対応 24Edge 完全対応 12Firefox 完全対応 29IE 完全対応 11Opera 完全対応 15Safari 完全対応 10WebView Android 未対応 なしChrome Android 完全対応 26Firefox Android 未対応 なしOpera Android 未対応 なしSafari iOS 完全対応 10Samsung Internet Android 完全対応 1.5nodejs 完全対応 13.0.0
完全対応 13.0.0
部分対応 0.12
補足
補足 Before version 13.0.0, only the locale data for en-US is available by default. When other locales are specified, the function silently falls back to en-US. To make full ICU (locale) data available for versions prior to 13, see Node.js documentation on the --with-intl option and how to provide the data.
optionsChrome 完全対応 24Edge 完全対応 12Firefox 完全対応 29IE 完全対応 11Opera 完全対応 15Safari 完全対応 10WebView Android 未対応 なしChrome Android 完全対応 26Firefox Android 未対応 なしOpera Android 未対応 なしSafari iOS 完全対応 10Samsung Internet Android 完全対応 1.5nodejs 完全対応 0.12

凡例

完全対応  
完全対応
未対応  
未対応
実装ノートを参照してください。
実装ノートを参照してください。

関連情報