path: root/files/ja/web/javascript/reference/global_objects/string/localecompare/index.html

---
title: String.prototype.localeCompare()
slug: Web/JavaScript/Reference/Global_Objects/String/localeCompare
tags:
  - Internationalization
  - JavaScript
  - Method
  - Prototype
  - Reference
  - String
translation_of: Web/JavaScript/Reference/Global_Objects/String/localeCompare
---
<div>{{JSRef("Global_Objects", "String")}}</div>

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

<div>{{EmbedInteractiveExample("pages/js/string-localecompare.html")}}</div>



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

<h2 id="Syntax" name="Syntax">構文</h2>

<pre class="syntaxbox notranslate"><code><var>referenceStr</var>.localeCompare(<var>compareString</var>[, <var>locales</var>[, <var>options</var>]])</code></pre>

<h3 id="Parameters" name="Parameters">引数</h3>

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

 <p>これらのパラメーターの詳細及び使用方法については <a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Collator/Collator"><code>Intl.Collator()</code> コンストラクター</a> を見てください。</p>
 </dd>
</dl>

<div>{{page('/docs/Web/JavaScript/Reference/Global_Objects/Collator', 'Parameters')}}</div>

<div>
<h3 id="戻り値">戻り値</h3>

<p><code><var>referenceStr</var></code> が <code><var>compareString</var></code> より前に出現する場合は負数、 <code><var>referenceStr</var></code> が <code><var>compareString</var></code> より後に出現する場合は正数、等しい場合は 0 。</p>
</div>

<h2 id="Description" name="Description">説明</h2>

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

<ul>
 <li><code><var>referenceStr</var></code> が <code><var>compareString</var></code> より先に出現する場合は負数</li>
 <li><code><var>referenceStr</var></code> が <code><var>compareString</var></code> より後に出現する場合は正数</li>
 <li>等しい場合は <code>0</code></li>
</ul>

<div class="blockIndicator warning">
<p><strong>戻り値が厳密に -1 や 1 であると考えないように</strong></p>

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

<h2 id="パフォーマンス">パフォーマンス</h2>

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

<h2 id="Examples" name="Examples">例</h2>

<h3 id="Example_Using_localeCompare" name="Example:_Using_localeCompare"><code>localeCompare()</code>を使う</h3>

<pre class="brush: js notranslate">// 文字 "a" は "c" は負数になります
'a'.localeCompare('c'); // -2 や -1 （あるいはまた別の負数）

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

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

<h3 id="配列のソート">配列のソート</h3>

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

<pre class="notranslate">let items = ['réservé', 'Premier', 'Cliché', 'communiqué', 'café', 'Adieu'];
items.sort( (a, b) =&gt; a.localeCompare(b, 'fr', {ignorePunctuation: true}));
// ['Adieu', 'café', 'Cliché', 'communiqué', 'Premier', 'réservé']
</pre>

<h3 id="Example_Checking_for_support_for_locales_and_options_arguments" name="Example:_Checking_for_support_for_locales_and_options_arguments">拡張された引数をブラウザーがサポートしているか調べる</h3>

<p>引数 <code><var>locales</var></code> と <code><var>options</var></code> はすべてのプラウザでまだサポートされていません。</p>

<p>実装がこれらをサポートしているか調べるため引数  <code>"i"</code> （不正な言語タグが除外される要件）を利用し、例外 {{jsxref("RangeError")}} を調べます。</p>

<pre class="brush: js notranslate">function localeCompareSupportsLocales() {
  try {
    'a'.localeCompare​('b', 'i');
  } catch (e) {
    return e​.name === 'RangeError';
  }
  return false;
}
</pre>

<h3 id="Example_Using_locales" name="Example:_Using_locales"><code>locales</code>を使う</h3>

<p><code>localeCompare()</code>によって得られる結果は言語間で違います。アプリケーションのユーザインターフェイスで使用される言語のソート順を得るために、 <code>locales</code>引数を使用してその言語(そしておそらくいくつかのフォールバック言語)を指定していることを確かめて下さい。:</p>

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

<h3 id="Example_Using_options" name="Example:_Using_options"><code>options</code>を使う</h3>

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

<pre class="brush: js notranslate">// ドイツ語では ä の base letter は a
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0

// スウェーデン語では ä と a は異なる base letters
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // a positive value
</pre>

<h3 id="数字のソート">数字のソート</h3>

<pre class="brush: js notranslate">// デフォルトでは "2" &gt; "10"
console.log(<span class="message-body-wrapper"><span class="message-flex-body"><span class="devtools-monospace message-body">"2".localeCompare("10")</span></span></span>); // 1

// オプションを使った数字
console.log(<span class="message-body-wrapper"><span class="message-flex-body"><span class="devtools-monospace message-body">"2".localeCompare("10", undefined, {numeric: true})</span></span></span>); // -1

// ロケールタグを使った数字
console.log(<span class="message-body-wrapper"><span class="message-flex-body"><span class="devtools-monospace message-body">"2".localeCompare("10", "en-u-kn-true")</span></span></span>); // -1
</pre>

<h2 id="仕様">仕様</h2>

<table>
 <thead>
  <tr>
   <th scope="col">Specification</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-string.prototype.localecompare', 'String.prototype.localeCompare')}}</td>
  </tr>
  <tr>
   <td>{{SpecName('ES Int Draft', '#sup-String.prototype.localeCompare', 'String.prototype.localeCompare')}}</td>
  </tr>
 </tbody>
</table>

<h2 id="ブラウザ実装状況">ブラウザ実装状況</h2>

<div>
<p>{{Compat("javascript.builtins.String.localeCompare")}}</p>
</div>

<h2 id="See_also" name="See_also">関連情報</h2>

<ul>
 <li>{{jsxref("Global_Objects/Collator", "Intl.Collator")}}</li>
</ul>