--- title: String.prototype.localeCompare() slug: Web/JavaScript/Reference/Global_Objects/String/localeCompare tags: - Internacionalização - JavaScript - Prototipo - Referencia - String - localeCompare() - metodo translation_of: Web/JavaScript/Reference/Global_Objects/String/localeCompare ---
{{JSRef}}

O método localeCompare() retorna um número que indica se uma string de referência vem antes ou depois, ou é a mesma que a string fornecida na ordem de classificação.

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

Os novos argumentos locales e options permitem que os aplicativos especifiquem o idioma cuja ordem da ordenação deve ser usada e personalizem o comportamento da função. Em implementações mais antigas, que ignoram os argumentos locales e options, a localidade e a ordem de classificação usadas são totalmente dependentes da implementação.

Sintaxe

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

Parâmetros

compareString
A string com a qual a referenceStr é comparada.
locales e options

Esses argumentos personalizam o comportamento da função e permitem que os aplicativos especifiquem o idioma cujas convenções de formatação devem ser usadas. Em implementações que ignoram os argumentos locales e options, a localidade usada e a forma da string retornada são inteiramente dependentes da implementação.

Consulte o construtor Intl.Collator() para obter detalhes sobre esses parâmetros e como usá-los.

Valor retornado

Um número negativo se referenceStr ocorrer antes de compareString. Um número positivo se o referenceStr ocorrer após compareString. 0 se eles forem equivalentes.

Descrição

Retorna um inteiro indicando se referenceStr vem antes, depois ou é equivalente a compareString.

NÃO confie em valores de retorno exatos de -1 ou 1!

Os resultados de números inteiros negativos e positivos variam entre os navegadores (bem como entre as versões dos navegadores) porque a especificação W3C exige apenas valores negativos e positivos. Alguns navegadores podem retornar -2 ou 2, ou mesmo algum outro valor negativo ou positivo.

Performance

Ao comparar um grande número de strings, como na classificação de grandes arrays, é melhor criar um objeto {{jsxref("Global_Objects/Collator", "Intl.Collator")}} e usar a função fornecida por sua propriedade {{jsxref("Collator.prototype.compare", "compare")}}.

Exemplos

Usando localeCompare()

// A letra "a" está antes de "c" produzindo um valor negativo
'a'.localeCompare('c'); // -2 ou -1 (ou algum outro valor negativo)

// Alfabeticamente, a palavra "verificar" vem depois de "contra", produzindo um valor positivo
'verificar'.localeCompare('contra'); // 2 ou 1 (ou algum outro valor positivo)

// "a" e "a" são equivalentes, resultando em um valor neutro de zero
'a'.localeCompare('a'); // 0

Ordenar um array

localeCompare() permite a ordenação sem distinção entre maiúsculas e minúsculas em um array.

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é']

Verifique o suporte do navegador para os novos argumentos

Os argumentos locales e options ainda não são suportados em todos os navegadores.

Para verificar se uma implementação os suporta, use o argumento "i" (um requisito de rejeição das tags de linguagem ilegal) e procure uma exceção {{jsxref ("RangeError")}}:

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

Usando locales

Os resultados fornecidos por localeCompare() variam entre os idiomas. Para obter a ordem de classificação do idioma usado na interface do usuário de seu aplicativo, certifique-se de especificar esse idioma (e possivelmente alguns idiomas substitutos) usando o argumento locales:

console.log('ä'.localeCompare('z', 'de')); // um valor negativo: em alemão, ä é classificado antes de z
console.log('ä'.localeCompare('z', 'sv')); // um valor positivo: em sueco, ä é classificado após z

Usando options

Os resultados fornecidos por localeCompare() podem ser personalizados usando o argumento options:

// em alemão, ä tem a como letra base
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0

// em sueco, ä e a são letras de base separadas
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // um valor positivo

Ordenação numérica

// por padrão, "2" > "10"
console.log("2".localeCompare("10")); // 1

// numeric using options:
console.log("2".localeCompare("10", undefined, {numeric: true})); // -1

// numeric using locales tag:
console.log("2".localeCompare("10", "en-u-kn-true")); // -1

Especificações

Especificação
{{SpecName('ESDraft', '#sec-string.prototype.localecompare', 'String.prototype.localeCompare')}}
{{SpecName('ES Int Draft', '#sup-String.prototype.localeCompare', 'String.prototype.localeCompare')}}

Compatibilidade com navegadores

{{Compat("javascript.builtins.String.localeCompare")}}

Veja também