String.prototype.localeCompare()
================================

Метод **`localeCompare()`** `строковых значений` возвращает число, указывающее, где должна находиться эта строка при сортировке (до, после или в том же самом месте, что и строка, переданная в качестве параметра). В реализациях с поддержкой `Intl.Collator` API этот метод просто вызывает `Intl.Collator`.

При сравнении большого количества строк, например при сортировке больших массивов, лучше создать объект `Intl.Collator` и использовать предоставляемый им метод `compare()`.

Интерактивный пример
--------------------

Синтаксис
---------


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

### Параметры

Параметры `locales` и `options`Параметры `locales` и `options` изменяют поведение функции и позволяют приложениям определять язык, правила форматирования которого, следует использовать.

В реализациях, поддерживающих `Intl.Collator` API, эти параметры соответствуют параметрам конструктора `Intl.Collator()` (en-US). Реализации без поддержки `Intl.Collator` должны игнорировать оба параметра, возвращаемый результат сравнения полностью зависит от реализации.

`compareString`

Строка, с которой сравнивается `referenceStr`. Все значения приводятся к строкам, поэтому отсутствие значения или значение `undefined` приводит к тому, что `localeCompare()` будет сравнивать со строкой `"undefined"`, а это скорее всего не то, что вы ожидаете.

`locales` Необязательный

Строка с языковым тегом BCP 47 или массив таких строк. Соответствует параметру `locales` (en-US) конструктора `Intl.Collator()`.

В реализациях без поддержки `Intl.Collator` этот параметр игнорируется и обычно используется локаль устройства.

`options` Необязательный

Объект определяющий выходной формат. Соответствует параметру `options` (en-US) конструктора `Intl.Collator()`.

В реализациях без поддержки `Intl.Collator` этот параметр игнорируется.

Смотрите описание конструктора `Intl.Collator()` (en-US) для подробностей использования параметров `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`!

Отрицательные и положительные ответы отличаются в зависимости от браузера (и версии браузера), потому что спецификация ECMAScript определяет только то, что числа должны быть положительными и отрицательными. Некоторые браузеры могут возвращать `-2` или `2` или другие значения.

Примеры
-------

### Использование `localeCompare()`


```js
// Буква "а" идёт перед "в", поэтому результат будет отрицательным
"а".localeCompare("в"); // -2 или -1 (или другое отрицательное число)

// В алфавитном порядке слово "первый" идёт после "второй", поэтому результат будет положительным
"первый".localeCompare("второй"); // 2 или 1 (или другое положительное число)

// "а" и "а" одинаковы, поэтому результат будет равен нулю
"а".localeCompare("а"); // 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é']
```

### Проверка поддержки параметров `locales` и `options`

Параметры `locales` и `options` поддерживаются ещё не всеми браузерами.

Чтобы проверить их поддержку реализацией, используйте аргумент `"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
// В немецком буква a является базовой для буквы ä
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0

// В шведском буквы ä и a являются двумя разными базовыми буквами
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // положительное значение
```

### Сортировка чисел


```js
// По умолчанию, "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 Language Specification # sec-string.prototype.localecompare |
| ECMAScript Internationalization API Specification # sup-String.prototype.localeCompare |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `Intl.Collator`