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

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.

Experimente
-----------

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()` (en-US) 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`*.

* Negativo quando o *`referenceStr`* ocorre antes de *`compareString`*
* Positivo quando o *`referenceStr`* ocorre após *`compareString`*
* Retorna `0` se eles forem equivalentes

**Aviso:** **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 `Intl.Collator` (en-US) e usar a função fornecida por sua propriedade `compare` (en-US).

Exemplos
--------

### Usando `localeCompare()`


```js
// 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.


```js
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 `RangeError` (en-US):


```js
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`*:


```js
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`*:


```js
// 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


```js
// 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
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.localecompare |
| ECMAScript Internationalization API Specification # sup-String.prototype.localeCompare |

Compatibilidade com navegadores
-------------------------------

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

Veja também
-----------

* `Intl.Collator` (en-US)