Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

String.prototype.localeCompare()

この記事は編集レビューを必要としています。ぜひご協力ください

この翻訳は不完全です。英語から この記事を翻訳 してください。

概要

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

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

構文

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

引数

どのブラウザがlocales引数とoptions引数をサポートしているか確かめるために、ブラウザ実装状況 セクションを調べて下さい。 特徴検出のために、例: locales引数とoptions引数をサポートしているか調べるを調べて下さい。

compareString
参照している文字列と比較する文字列
locales

Optional. A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the locales argument, see the Intl page. The following Unicode extension keys are allowed:

co
Variant collations for certain locales. Possible values include: "big5han", "dict", "direct", "ducet", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan". The "standard" and "search" values are ignored; they are replaced by the options property usage (see below).
kn
Whether numeric collation should be used, such that "1" < "2" < "10". Possible values are "true" and "false". This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence.
kf
Whether upper case or lower case should sort first. Possible values are "upper", "lower", or "false" (use the locale's default). This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence.
options

Optional. An object with some or all of the following properties:

localeMatcher
The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see the Intl page.
usage
Whether the comparison is for sorting or for searching for matching strings. Possible values are "sort" and "search"; the default is "sort".
sensitivity

Which differences in the strings should lead to non-zero result values. Possible values are:

  • "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A.
  • "accent": Only strings that differ in base letters or accents and other diacritic marks compare as unequal. Examples: a ≠ b, a ≠ á, a = A.
  • "case": Only strings that differ in base letters or case compare as unequal. Examples: a ≠ b, a = á, a ≠ A.
  • "variant": Strings that differ in base letters, accents and other diacritic marks, or case compare as unequal. Other differences may also be taken into consideration. Examples: a ≠ b, a ≠ á, a ≠ A.

The default is "variant" for usage "sort"; it's locale dependent for usage "search".

ignore­Punctua­tion
Whether punctuation should be ignored. Possible values are true and false; the default is false.
numeric
Whether numeric collation should be used, such that "1" < "2" < "10". Possible values are true and false; the default is false. This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence. Implementations are not required to support this property.
caseFirst
Whether upper case or lower case should sort first. Possible values are "upper", "lower", or "false" (use the locale's default); the default is "false". This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence. Implementations are not required to support this property.

説明

参照文字列がソート順に引数で与えられた文字列と大なり、小なり、等しいかを示す数値を返します。参照文字列がソート順でcompareStringより前になったら負の数を返します。参照文字列がソート順で後になったら正の数を返します。等しいなら、0を返します。

例: localeCompare()を使う

次の例では、ある文字列が大なり、小なり、等しいとなる異なる潜在的な結果を実証します。:

console.log('a'.localeCompare('c')); // -2, or -1, or some other negative value
console.log('c'.localeCompare('a')); // 2, or 1, or some other positive value
console.log('a'.localeCompare('a')); // 0

上記のコードで示される結果はブラウザ間やバージョン間で異なることに注意して下さい。値が実装依存のためです。すなわち、仕様では小なり、大なりの値は、負の値、正の値であることのみ要求しています。

例: locales引数とoptions引数をサポートしているか調べる

locales引数とoptions引数はすべてのプラウザでまだサポートされていません。実装がすでにサポートしているか調べるために、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 negative value: in German, ä sorts with a
console.log('ä'.localeCompare('z', 'sv')); // a positive value: in Swedish, ä sorts after z

例: optionsを使う

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

// in German, ä has a as the base letter
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0

// in Swedish, ä and a are separate base letters
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // a positive value

性能

大きな配列をソートするような、多数の文字列を比較するとき、Intl.Collatorオブジェクトを生成して、compareプロパティによって得られる関数を使用するほうが良いです。

仕様

仕様 状況 コメント
ECMAScript 3rd Edition. Standard Initial definition. Implemented in JavaScript 1.2.
ECMAScript 5.1 (ECMA-262)
The definition of 'String.prototype.localeCompare' in that specification.
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'String.prototype.localeCompare' in that specification.
Standard  
ECMAScript Internationalization API 1.0 (ECMA-402)
The definition of 'String.prototype.localeCompare' in that specification.
Standard locale and option parameter defintions

ブラウザ実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本サポート (有) (有) (有) (有) (有)
locales引数とoptions引数 24 29 (29) 11 15 未サポート
機能 Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
基本サポート (有) (有) (有) (有) (有) (有)
locales引数とoptions引数 未サポート 26 未サポート
バグ 864843
未サポート 未サポート 未サポート

関連情報

ドキュメントのタグと貢献者

 このページの貢献者: shide55
 最終更新者: shide55,