String.prototype.localeCompare()

Метод localeCompare() повертає число, яке вказує, як має розташуватись рядок відносно вказаного (того, що передано як параметр) у відсортованій за зростанням послідовності: перед, після, чи вони однакові.

Нові арґументи locales та options дають можливість вказати мову, абетковий порядок сортування якої має бути застосовано, та налаштувати механізм порівняння рядків. Раніше, коли цих арґументів ще не було, механізм порівняння рядків та порядок їх сортування цілковито залежав від реалізації.

Синтаксис

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

Параметри

Перевіряйте в таблиці сумісності наявність підтримки арґументів locales та options, а також подивіться на код для перевірки наявності такої підтримки.

compareString
Рядок, з яким буде здійснено порівняння.

Аргументи locales та options налаштовують поведінку функції та дозволяють застосункам визначати мову, конвенції якої щодо форматування мають використовуватись. У тих реалізаціях, які ігнорують аргументи locales та options, локаль, що використовується, та форма поверненого рядка повністю залежать від реалізації.

Деталі цих параметрів та як їх використовувати дивіться у статті Конструктор Intl.Collator().

Вертає

  • Від'ємне число, якщо рядок має розташуватись перед compareString;
  • Додатне число, якщо рядок має розташуватись після compareString;
  • Нуль, якщо рядки тотожні.

Опис

Вертає ціле число, що вказує, чи рядок referenceStr розташований перед compareStr, після compareStr, чи є еквівалентним compareStr.

  • Від'ємне, коли referenceStr розташований перед compareStr
  • Додатне, коли referenceStr розташований після compareStr
  • Вертає 0, якщо вони еквівалентні

НЕ ПОКЛАДАЙТЕСЬ на точні повернені значення -1 чи 1. Від'ємні та додатні цілочисельні результати різняться між переглядачами (а також між версіями переглядачів), тому що специфікація W3C вимагає лише від'ємних та додатних значень. Деякі переглядачі можуть повернути -2 чи 2, чи навіть деякі інші від'ємні та додатні значення.

Приклади

Використання localeCompare()

// Вертає від'ємне значення, позаяк літера «a» розташована раніше за «b»
'a'.localeCompare('c');  // -2 чи -1 (або інше від'ємне значення)

// Вертає додатне значення, позаяк за абеткою слово "check" слід розташувати після "against"
'check'.localeCompare('against');  // 2 чи 1 (або інше додатне значення)

// Вертає нуль, позаяк рядки однакові
'a'.localeCompare('a');  // 0

Сортування масиву

Метод localeCompare() надає можливість регістронезалежного сортування масивів:

var 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 досі не підтримуються всіма переглядачами. Тож, з метою з'ясування наявності підтримки можна скористатися тим, що метод викидає (лише за наявності такої підтримки згаданих арґументів) виняток RangeError, якщо параметр locales не вказує належного мовного коду. Наприклад, вкажемо напевне відсутній код "i":

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

Використання locales

Порівняння рядків за допомогою localeCompare() узалежнено від мови. Для застосування належного для вживаної мови (наприклад, для мови користувацького інтерфейсу вашого застосунку) порядку сортування, не забудьте вказати відповідний мовний код (або й запасні мовні коди) через параметр locales:

// виводить від'ємне значення (у німецькій абетці літера «ä» розташована раніше «z»)
console.log('ä'.localeCompare('z', 'de'));

// виводить додатне значення (у шведській абетці літера «ä» розташована пізніше «z»)
console.log('ä'.localeCompare('z', 'sv'));

Використання options

Арґумент options надає можливість додаткового налаштування способу порівняння рядків методом localeCompare():

// У німецькій мові літера «ä» є похідною від базової літери «a»
// виводить 0
console.log('ä'.localeCompare('a', 'de', {sensitivity: 'base'}));

// У шведській мові «ä» та «a» є окремими базовими літерами
// виводить додатне значення
console.log('ä'.localeCompare('a', 'sv', {sensitivity: 'base'}));

Сортування чисел

// за замовчуванням, "2" > "10"
console.log("2".localeCompare("10")); // 1

// сортування за допомогою options:
console.log("2".localeCompare("10", undefined, {numeric: true})); // -1

// сортування за допомогою тега locales:
console.log("2".localeCompare("10", "en-u-kn-true")); // -1

Швидкодія

З огляду на швидкодію, для порівняння величезної кількості рядків (наприклад, під час сортування великих масивів) ліпше створювати об'єкт Intl.Collator та використовувати функцію, надану його властивістю compare:

function sortLargeStringArray(array, locale) {
  var collator = new Intl.Collator(locale);
  array.sort(collator.compare);
}

// sortLargeStringArray([ … ], 'uk');

Специфікації

Специфікація
ECMAScript (ECMA-262)
The definition of 'String.prototype.localeCompare' in that specification.
ECMAScript Internationalization API (ECMA-402)
The definition of 'String.prototype.localeCompare' in that specification.

Підтримка веб-переглядачами

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
localeCompareChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 5.5Opera Full support 7Safari Full support 3WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0nodejs Full support 0.1.100
localesChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android No support NoOpera Android No support NoSafari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support 13.0.0
Full support 13.0.0
Partial support 0.12
Notes
Notes 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 Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android No support NoOpera Android No support NoSafari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support 0.12

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Див. також